@oracle-agent/oracle 0.4.2 → 0.6.0

package/src/cli/kernel.mjs

@@ -0,0 +1,237 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { PACKAGE_ROOT, paths } from "./paths.mjs";
+import {
+  dispatchOperator,
+  resolveOperator,
+  printOperatorNotInstalled,
+  SIGN_NOUNS,
+} from "./operator-dispatch.mjs";
+
+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
+  oracle route swap|bridge|prepare|prepare-bridge
+  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
+
+SIGNING (dispatches to @oracle-agent/operator on THIS machine; never in this package)
+  oracle sign init|doctor     provision / check the local signer (opt-in)
+  oracle vault ...            encrypt local key files at rest
+  oracle signer / runner      loopback signer daemon / action runner
+  oracle credential ...       OS credential store glue
+
+oracle <noun> --help for details. Keys never leave your machine; this package
+cannot sign — signing commands run the locally installed operator package.
+`;
+
+function readPackageVersion() {
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+    );
+    return pkg.version || "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+export function commandsDir() {
+  return path.join(PACKAGE_ROOT, "src", "cli", "commands");
+}
+
+export async function discoverCommands() {
+  const dir = commandsDir();
+  const out = new Map();
+  if (!fs.existsSync(dir)) return out;
+  const entries = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".mjs"))
+    .sort();
+  for (const file of entries) {
+    const full = path.join(dir, file);
+    try {
+      const mod = await import(pathToFileURL(full).href + `?t=${Date.now()}`);
+      const cmd = mod.default;
+      if (!cmd || typeof cmd !== "object" || typeof cmd.run !== "function") {
+        continue;
+      }
+      const name = cmd.name || file.replace(/\.mjs$/, "");
+      out.set(name, { ...cmd, name, __file: full });
+    } catch (err) {
+      if (process.env.ORACLE_CLI_DEBUG) {
+        console.error(`oracle: failed loading command ${file}: ${err.message}`);
+      }
+    }
+  }
+  return out;
+}
+
+export function renderHelp(version, commands) {
+  const lines = [];
+  lines.push(`${HELP_HEADER} (v${version})`);
+  lines.push("");
+  lines.push(STATIC_HELP.trimEnd());
+
+  const extras = [];
+  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",
+      "sign","vault","signer","runner","credential",
+    ]);
+    if (!known.has(cmd.name) && cmd.summary) {
+      extras.push(`  oracle ${cmd.name.padEnd(20)} ${cmd.summary}`);
+    }
+  }
+  if (extras.length) {
+    lines.push("");
+    lines.push("ADDITIONAL");
+    lines.push(...extras);
+  }
+  return lines.join("\n") + "\n";
+}
+
+function unknownNounMessage(noun, commands) {
+  const known = [...commands.keys()].sort();
+  const list = known.length ? known.join(", ") : "(none loaded yet)";
+  return `oracle: unknown command '${noun}'. Known: ${list}\nTry: oracle --help\n`;
+}
+
+function buildCtx(argv) {
+  return {
+    argv,
+    root: PACKAGE_ROOT,
+    paths,
+    dispatchOperator,
+    resolveOperator,
+  };
+}
+
+export async function run(argv = []) {
+  const version = readPackageVersion();
+
+  if (argv.includes("--version") || argv.includes("-V")) {
+    return runVersion();
+  }
+  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);
+
+  if (noun === "version") {
+    return runVersion();
+  }
+  if (noun === "help") {
+    const commands = await discoverCommands();
+    if (rest[0]) {
+      const cmd = commands.get(rest[0]);
+      if (cmd) {
+        process.stdout.write((cmd.usage || `oracle ${cmd.name}`) + "\n");
+        if (cmd.summary) process.stdout.write(cmd.summary + "\n");
+        return 0;
+      }
+      process.stderr.write(unknownNounMessage(rest[0], commands));
+      return 1;
+    }
+    process.stdout.write(renderHelp(version, commands));
+    return 0;
+  }
+
+  const commands = await discoverCommands();
+  const cmd = commands.get(noun);
+
+  if (cmd) {
+    if (rest[0] === "--help" || rest[0] === "-h") {
+      process.stdout.write((cmd.usage || `oracle ${cmd.name}`) + "\n");
+      if (cmd.summary) process.stdout.write(cmd.summary + "\n");
+      return 0;
+    }
+    try {
+      const code = await cmd.run(buildCtx(rest));
+      return typeof code === "number" ? code : 0;
+    } catch (err) {
+      process.stderr.write(`oracle ${noun}: ${err?.message || err}\n`);
+      return 1;
+    }
+  }
+
+  if (SIGN_NOUNS.includes(noun)) {
+    const resolved = resolveOperator();
+    if (!resolved.ok) {
+      printOperatorNotInstalled(process.stderr);
+      return 3;
+    }
+    process.stderr.write(
+      `oracle: sign-plane command '${noun}' is not available in this build (operator is installed).\n`,
+    );
+    return 1;
+  }
+
+  process.stderr.write(unknownNounMessage(noun, commands));
+  return 1;
+}
+
+async function runVersion() {
+  const version = readPackageVersion();
+  let line = `oracle ${version}`;
+  const op = resolveOperator();
+  if (op.ok) {
+    line += `  operator ${op.version}`;
+  }
+  process.stdout.write(line + "\n");
+  return 0;
+}
+
+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 || ""));
+}

package/src/cli/mcp-targets/chatgpt.mjs

@@ -0,0 +1,51 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, report } from "./shared.mjs";
+
+export const CHATGPT_CANNOT_SIGN =
+  "ChatGPT is hosted and can NEVER sign or reach your keys. This connector is read/prepare only; anything it prepares is unsigned until you sign it locally.";
+
+function openApiDoc() {
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: "Oracle Public (read/prepare)",
+      version: "1.0.0",
+      description: "Secret-free public surface for hosted clients. " + CHATGPT_CANNOT_SIGN,
+    },
+    servers: [{ url: "https://REPLACE-WITH-YOUR-TUNNEL" }],
+    paths: {
+      "/public/health": { get: { operationId: "publicHealth", summary: "Health check", responses: { "200": { description: "ok" } } } },
+      "/public/config": { get: { operationId: "publicConfig", summary: "Public config", responses: { "200": { description: "ok" } } } },
+      "/public/connect/request": { post: { operationId: "connectRequest", summary: "Build a connect request (unsigned)", responses: { "200": { description: "unsigned request artifact" } } } },
+      "/public/connect/assemble": { post: { operationId: "connectAssemble", summary: "Assemble an unsigned grant artifact", responses: { "200": { description: "unsigned grant artifact" } } } },
+      "/public/grants/active": { post: { operationId: "grantsActive", summary: "List active grants (read)", responses: { "200": { description: "ok" } } } },
+      "/public/grants/get": { post: { operationId: "grantsGet", summary: "Get a grant by id (read)", responses: { "200": { description: "ok" } } } },
+    },
+  };
+}
+
+export async function installChatgpt({ printOnly = false } = {}) {
+  const doc = openApiDoc();
+  const target = path.join(fakeHome(), ".config", "oracle", "connectors", "chatgpt-openapi.json");
+  const text = JSON.stringify(doc, null, 2) + "\n";
+  if (!printOnly) {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, text);
+  }
+  const instructions = [
+    CHATGPT_CANNOT_SIGN, "",
+    "Next steps:",
+    "  1. oracle public serve",
+    "  2. Expose 127.0.0.1:8799 through YOUR HTTPS tunnel (cloudflared, tailscale funnel, etc.).",
+    "     Oracle will not create tunnels for you.",
+    "  3. Paste the OpenAPI spec into a GPT Action, or add the tunnel URL as a developer-mode MCP connector.",
+    printOnly ? "" : `  Spec written to: ${target}`,
+  ].filter(Boolean).join("\n");
+  return {
+    ok: true,
+    ...report(printOnly ? "printed" : "written", {
+      path: target, print: doc, instructions, cannotSign: CHATGPT_CANNOT_SIGN,
+    }),
+  };
+}

package/src/cli/mcp-targets/claude-code.mjs

@@ -0,0 +1,39 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, mergeMcpServers, report } from "./shared.mjs";
+
+function claudeJsonPath() { return path.join(fakeHome(), ".claude.json"); }
+function projectMcpPath(cwd) { return path.join(cwd || process.cwd(), ".mcp.json"); }
+
+function tryClaudeCli(name, spec) {
+  const probe = spawnSync("claude", ["--version"], { encoding: "utf8", timeout: 10000 });
+  if (probe.error || probe.status !== 0) return null;
+  const r = spawnSync("claude", ["mcp", "add-json", name, JSON.stringify(spec), "--scope", "user"], {
+    encoding: "utf8", timeout: 30000,
+  });
+  if (r.status !== 0) return { ok: false, stderr: r.stderr || r.stdout || "failed" };
+  return { ok: true };
+}
+
+export async function installClaudeCode({
+  oracleRoot, operator, withControl = false, project = false, printOnly = false, cwd = process.cwd(),
+}) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  if (printOnly) return { ok: true, print: { mcpServers: built.specs } };
+  if (project) {
+    const target = projectMcpPath(cwd);
+    const result = mergeMcpServers(target, built.specs);
+    return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+  }
+  let usedCli = false;
+  for (const [name, spec] of Object.entries(built.specs)) {
+    const cli = tryClaudeCli(name, spec);
+    if (cli && cli.ok) { usedCli = true; continue; }
+    break;
+  }
+  if (usedCli) return { ok: true, ...report("written", { method: "claude-cli" }) };
+  const target = claudeJsonPath();
+  const result = mergeMcpServers(target, built.specs);
+  return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+}

package/src/cli/mcp-targets/claude-desktop.mjs

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, mergeMcpServers, report } from "./shared.mjs";
+
+function desktopConfigPath() {
+  if (process.platform === "darwin") {
+    return path.join(fakeHome(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  return path.join(fakeHome(), ".config", "Claude", "claude_desktop_config.json");
+}
+
+export async function installClaudeDesktop({ oracleRoot, operator, withControl = false, printOnly = false }) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  const target = desktopConfigPath();
+  const payload = { mcpServers: built.specs };
+  if (printOnly) return { ok: true, print: payload };
+  const parent = path.dirname(target);
+  if (!fs.existsSync(parent)) {
+    return { ok: true, status: "printed (Claude Desktop not detected)", path: target, print: payload };
+  }
+  const result = mergeMcpServers(target, built.specs);
+  return { ok: true, ...report(result.status, { path: target, backup: result.backup }) };
+}

package/src/cli/mcp-targets/codex.mjs

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fakeHome, buildServerSpecs, backupFile, report } from "./shared.mjs";
+
+const BEGIN = "# oracle-mcp-install begin";
+const END = "# oracle-mcp-install end";
+
+function codexPath() { return path.join(fakeHome(), ".codex", "config.toml"); }
+
+function renderBlock(specs) {
+  const lines = [BEGIN];
+  for (const [name, spec] of Object.entries(specs)) {
+    lines.push(`[mcp_servers.${name}]`);
+    lines.push(`command = ${JSON.stringify(spec.command)}`);
+    lines.push(`args = [${spec.args.map((a) => JSON.stringify(a)).join(", ")}]`);
+    lines.push("");
+  }
+  lines.push(END);
+  return lines.join("\n") + "\n";
+}
+
+function stripExistingBlock(text) {
+  return text.replace(new RegExp(`${BEGIN}[\\s\\S]*?${END}\\n?`, "g"), "");
+}
+
+export async function installCodex({ oracleRoot, operator, withControl = false, printOnly = false }) {
+  const built = buildServerSpecs({ oracleRoot, operator, withControl });
+  if (!built.ok) return { ok: false, code: 3, reason: built.reason };
+  const block = renderBlock(built.specs);
+  const target = codexPath();
+  if (printOnly) return { ok: true, printText: block, path: target };
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const prev = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : "";
+  if (prev.includes(block.trim())) return { ok: true, ...report("present", { path: target, backup: null }) };
+  const stripped = stripExistingBlock(prev);
+  const next = (stripped.trimEnd() + "\n\n" + block).replace(/^\n+/, "");
+  if (prev.trim() === next.trim()) return { ok: true, ...report("present", { path: target, backup: null }) };
+  const backup = prev ? backupFile(target) : null;
+  fs.writeFileSync(target, next.endsWith("\n") ? next : next + "\n");
+  return { ok: true, ...report("written", { path: target, backup }) };
+}

package/src/cli/mcp-targets/shared.mjs

@@ -0,0 +1,61 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { PACKAGE_ROOT } from "../paths.mjs";
+
+export function fakeHome() {
+  return process.env.ORACLE_FAKE_HOME || os.homedir();
+}
+
+export function buildServerSpecs({ oracleRoot = PACKAGE_ROOT, operator = null, withControl = false } = {}) {
+  const specs = {
+    "oracle-data": {
+      command: "node",
+      args: [path.join(oracleRoot, "bin", "oracle-data-mcp.mjs")],
+    },
+  };
+  if (withControl) {
+    if (!operator || !operator.ok) return { ok: false, reason: "operator-missing" };
+    const control = operator.bins?.["oracle-control-mcp"] || operator.controlMcp || null;
+    if (!control) return { ok: false, reason: "control-bin-missing" };
+    specs["oracle-control"] = { command: "node", args: [control] };
+  }
+  return { ok: true, specs };
+}
+
+export function backupFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const bak = `${filePath}.bak-oracle-${Math.floor(Date.now() / 1000)}`;
+  fs.copyFileSync(filePath, bak);
+  return bak;
+}
+
+export function readJson(filePath, fallback = {}) {
+  if (!fs.existsSync(filePath)) return structuredClone(fallback);
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function writeJson(filePath, obj) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(obj, null, 2) + "\n");
+}
+
+export function mergeMcpServers(filePath, specs) {
+  const existing = readJson(filePath, {});
+  if (!existing.mcpServers || typeof existing.mcpServers !== "object") existing.mcpServers = {};
+  let changed = false;
+  for (const [name, spec] of Object.entries(specs)) {
+    const prev = existing.mcpServers[name];
+    if (prev && JSON.stringify(prev) === JSON.stringify(spec)) continue;
+    existing.mcpServers[name] = spec;
+    changed = true;
+  }
+  if (!changed) return { status: "present", backup: null };
+  const backup = backupFile(filePath);
+  writeJson(filePath, existing);
+  return { status: "written", backup };
+}
+
+export function report(status, detail = {}) {
+  return { status, ...detail };
+}

package/src/cli/messaging-platforms.mjs

@@ -0,0 +1,209 @@
+// Hermes messaging platforms Oracle can configure.
+// Values stay lowercase. Secrets stay in Hermes profile .env, never printed.
+
+export const MESSAGING_PLATFORMS = Object.freeze([
+  {
+    key: "telegram",
+    name: "telegram",
+    hermes: ["gateway", "setup"],
+    required: ["TELEGRAM_BOT_TOKEN"],
+    optional: ["TELEGRAM_ALLOWED_USERS", "TELEGRAM_PROXY"],
+    note: "dms · groups · topics",
+  },
+  {
+    key: "discord",
+    name: "discord",
+    hermes: ["gateway", "setup"],
+    required: ["DISCORD_BOT_TOKEN"],
+    optional: ["DISCORD_ALLOWED_USERS"],
+    note: "dms · channels · threads",
+  },
+  {
+    key: "slack",
+    name: "slack",
+    hermes: ["gateway", "setup"],
+    required: ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"],
+    optional: ["SLACK_ALLOWED_USERS"],
+    note: "socket mode",
+  },
+  {
+    key: "whatsapp",
+    name: "whatsapp",
+    hermes: ["whatsapp"],
+    required: [],
+    optional: ["WHATSAPP_ALLOWED_USERS", "WHATSAPP_MODE"],
+    note: "qr bridge",
+  },
+  {
+    key: "whatsapp-cloud",
+    name: "whatsapp cloud",
+    hermes: ["whatsapp-cloud"],
+    required: [],
+    optional: [],
+    note: "business cloud api",
+  },
+  {
+    key: "signal",
+    name: "signal",
+    hermes: ["gateway", "setup"],
+    required: ["SIGNAL_HTTP_URL", "SIGNAL_ACCOUNT"],
+    optional: ["SIGNAL_ALLOWED_USERS"],
+    note: "signal-cli rest bridge",
+  },
+  {
+    key: "matrix",
+    name: "matrix",
+    hermes: ["gateway", "setup"],
+    required: ["MATRIX_HOMESERVER", "MATRIX_ACCESS_TOKEN", "MATRIX_USER_ID"],
+    optional: ["MATRIX_ALLOWED_USERS"],
+    note: "rooms · dms",
+  },
+  {
+    key: "mattermost",
+    name: "mattermost",
+    hermes: ["gateway", "setup"],
+    required: ["MATTERMOST_URL", "MATTERMOST_TOKEN"],
+    optional: ["MATTERMOST_ALLOWED_USERS"],
+    note: "channels · dms",
+  },
+  {
+    key: "email",
+    name: "email",
+    hermes: ["gateway", "setup"],
+    required: ["EMAIL_ADDRESS", "EMAIL_PASSWORD", "EMAIL_IMAP_HOST", "EMAIL_SMTP_HOST"],
+    optional: [],
+    note: "imap/smtp mailbox",
+  },
+  {
+    key: "bluebubbles",
+    name: "bluebubbles",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "imessage via bluebubbles",
+  },
+  {
+    key: "homeassistant",
+    name: "homeassistant",
+    hermes: ["gateway", "setup"],
+    required: ["HASS_URL", "HASS_TOKEN"],
+    optional: [],
+    note: "smart home",
+  },
+  {
+    key: "webhook",
+    name: "webhook",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "http ingress",
+  },
+  {
+    key: "api-server",
+    name: "api server",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "local http api",
+  },
+  {
+    key: "dingtalk",
+    name: "dingtalk",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "dingtalk bot",
+  },
+  {
+    key: "feishu",
+    name: "feishu",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "feishu / lark",
+  },
+  {
+    key: "wecom",
+    name: "wecom",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "wecom",
+  },
+  {
+    key: "weixin",
+    name: "weixin",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "weixin",
+  },
+  {
+    key: "qqbot",
+    name: "qqbot",
+    hermes: ["gateway", "setup"],
+    required: [],
+    optional: [],
+    note: "qq bot",
+  },
+]);
+
+function normalize(raw) {
+  return String(raw || "")
+    .trim()
+    .toLowerCase()
+    .replace(/^\/+/, "")
+    .replace(/\s+/g, "-");
+}
+
+export function listMessagingPlatforms() {
+  return MESSAGING_PLATFORMS.slice();
+}
+
+export function findMessagingPlatform(query) {
+  const q = normalize(query);
+  if (!q) return null;
+  for (const p of MESSAGING_PLATFORMS) {
+    if (p.key === q) return p;
+    if (normalize(p.name) === q) return p;
+  }
+  return null;
+}
+
+export function renderSetupMenu({ profile = "oracle", statuses = {} } = {}) {
+  const lines = [
+    "oracle setup",
+    "",
+    "one oracle. many models. hermes messaging underneath.",
+    `profile: ${profile}`,
+    "",
+    "messaging platforms:",
+    "",
+  ];
+  for (const p of MESSAGING_PLATFORMS) {
+    const st = statuses[p.key] || "unset";
+    lines.push(`  ${p.key.padEnd(16)} ${String(st).padEnd(8)}  ${p.note}`);
+  }
+  lines.push("");
+  lines.push("commands:");
+  lines.push("  oracle setup                 this menu");
+  lines.push("  oracle setup messaging       open hermes gateway setup");
+  lines.push("  oracle setup telegram        configure telegram bot token");
+  lines.push("  oracle setup discord         configure discord bot token");
+  lines.push("  oracle setup status          show configured platforms (no secrets)");
+  lines.push("  oracle setup gateway         start/status hermes gateway");
+  lines.push("  /setup                       same menu inside chat");
+  lines.push("");
+  lines.push("notes:");
+  lines.push("  tokens stay in the hermes profile .env on this machine");
+  lines.push("  oracle never prints bot tokens or app secrets");
+  lines.push("  after setup: hermes -p oracle gateway restart");
+  return lines.join("\n") + "\n";
+}
+
+export default {
+  MESSAGING_PLATFORMS,
+  listMessagingPlatforms,
+  findMessagingPlatform,
+  renderSetupMenu,
+};