@oracle-agent/oracle 0.5.0 → 0.7.0

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,
+};

package/src/cli/oracle-harness.py

@@ -0,0 +1,148 @@
+import importlib
+import importlib.abc
+import importlib.machinery
+import re
+import sys
+
+LOGO = (
+    "                 _",
+    " ___ _ _ __ _ __| |___",
+    "/ _ \\ '_/ _` / _| / -_)",
+    "\\___/_| \\__,_\\__|_\\___|",
+)
+
+SILENT_STDERR = {
+    "[anthropic_billing_bypass] Bypass installed",
+    "[anthropic_billing_bypass] Transport unwrap hook installed",
+}
+
+
+class OracleStderr:
+    def __init__(self, wrapped):
+        self.wrapped = wrapped
+
+    def write(self, data):
+        kept = "".join(
+            line
+            for line in data.splitlines(keepends=True)
+            if line.rstrip("\r\n") not in SILENT_STDERR
+        )
+        if kept:
+            self.wrapped.write(kept)
+        return len(data)
+
+    def flush(self):
+        return self.wrapped.flush()
+
+    def __getattr__(self, name):
+        return getattr(self.wrapped, name)
+
+
+def patch_cli(module):
+    hermes_cli = getattr(module, "HermesCLI")
+    original_layout = hermes_cli._build_tui_layout_children
+    original_emit = hermes_cli._emit_stream_text
+    original_flush = hermes_cli._flush_stream
+    original_cprint = getattr(module, "_cprint")
+    frame_filter = [0]
+
+    def cprint(text="", *args, **kwargs):
+        if frame_filter[0] and isinstance(text, str):
+            plain = re.sub(r"\x1b\[[0-9;]*m", "", text).lstrip("\n")
+            if plain.startswith("\u256d\u2500oracle") or plain.startswith("\u2570"):
+                return None
+        return original_cprint(text, *args, **kwargs)
+
+    setattr(module, "_cprint", cprint)
+
+    def show_banner(self):
+        self.console.clear()
+        self._console_print()
+        for line in LOGO:
+            self._console_print(f"[#e6edf3]{line}[/]")
+        self._console_print()
+
+    def prompt_fragments(self):
+        if self._approval_state or getattr(self, "_slash_confirm_state", None):
+            marker = "!"
+        elif self._clarify_state or self._clarify_freetext:
+            marker = "?"
+        elif self._command_running or self._agent_running:
+            marker = "..."
+        else:
+            marker = ">"
+        return [("class:prompt", f"oracle {marker} ")]
+
+    def layout_children(self, **kwargs):
+        kwargs["status_bar"] = None
+        kwargs["input_rule_top"] = None
+        kwargs["input_rule_bot"] = None
+        return original_layout(self, **kwargs)
+
+    def emit_stream_text(self, text):
+        first = not self._stream_box_opened
+        if first:
+            original_cprint()
+        frame_filter[0] += 1
+        try:
+            return original_emit(self, text)
+        finally:
+            frame_filter[0] -= 1
+
+    def flush_stream(self):
+        frame_filter[0] += 1
+        try:
+            return original_flush(self)
+        finally:
+            frame_filter[0] -= 1
+
+    hermes_cli.show_banner = show_banner
+    hermes_cli._get_tui_prompt_fragments = prompt_fragments
+    hermes_cli._build_tui_layout_children = layout_children
+    hermes_cli._emit_stream_text = emit_stream_text
+    hermes_cli._flush_stream = flush_stream
+    tips = importlib.import_module("hermes_cli.tips")
+
+    def no_tip():
+        raise LookupError("oracle quiet startup")
+
+    setattr(tips, "get_random_tip", no_tip)
+
+
+class OracleLoader(importlib.abc.Loader):
+    def __init__(self, wrapped):
+        self.wrapped = wrapped
+
+    def create_module(self, spec):
+        if hasattr(self.wrapped, "create_module"):
+            return self.wrapped.create_module(spec)
+        return None
+
+    def exec_module(self, module):
+        self.wrapped.exec_module(module)
+        patch_cli(module)
+
+
+class OracleFinder(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path, target=None):
+        if fullname != "cli":
+            return None
+        try:
+            sys.meta_path.remove(self)
+        except ValueError:
+            pass
+        spec = importlib.machinery.PathFinder.find_spec(fullname, path)
+        if spec and spec.loader:
+            spec.loader = OracleLoader(spec.loader)
+        return spec
+
+
+def main():
+    sys.stderr = OracleStderr(sys.stderr)
+    sys.meta_path.insert(0, OracleFinder())
+    hermes_main = getattr(importlib.import_module("hermes_cli.main"), "main")
+    return hermes_main()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/cli/paths.mjs

@@ -50,6 +50,10 @@ export function chatgptOpenApiPath() {
   return path.join(chatgptConnectorDir(), "chatgpt-openapi.json");
 }
 
+export function activeChainPath() {
+  return path.join(oracleConfigDir(), "active-chain.json");
+}
+
 export function packageBin(name) {
   return path.join(PACKAGE_ROOT, "bin", name);
 }
@@ -64,6 +68,7 @@ export const paths = {
   oracleConfigDir,
   oracleExecEnvPath,
   hermesRoot,
+  activeChainPath,
   claudeCodeUserConfigPath,
   claudeCodeProjectMcpPath,
   claudeDesktopConfigPath,

package/src/cli/setup-state.mjs

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  listMessagingPlatforms,
+  findMessagingPlatform,
+  renderSetupMenu,
+} from "./messaging-platforms.mjs";
+import { hermesRoot, ensureDir, oracleConfigDir } from "./paths.mjs";
+
+const SECRETISH = /(TOKEN|SECRET|PASSWORD|KEY|AUTH|PRIVATE|MNEMONIC|SEED)/i;
+
+export function profileEnvPath(profile = "oracle") {
+  return path.join(hermesRoot(), "profiles", profile, ".env");
+}
+
+export function parseDotEnv(text) {
+  const out = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+export function readProfileEnv(profile = "oracle") {
+  const p = profileEnvPath(profile);
+  if (!fs.existsSync(p)) return {};
+  return parseDotEnv(fs.readFileSync(p, "utf8"));
+}
+
+export function writeProfileEnvKey(profile, key, value) {
+  if (!key || SECRETISH.test(key) === false && /[^A-Z0-9_]/.test(key)) {
+    // keep simple env keys
+  }
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+    const err = new Error(`invalid env key '${key}'`);
+    err.code = "BAD_KEY";
+    throw err;
+  }
+  if (value == null || String(value).trim() === "") {
+    const err = new Error(`empty value for ${key}`);
+    err.code = "EMPTY";
+    throw err;
+  }
+  const p = profileEnvPath(profile);
+  ensureDir(path.dirname(p));
+  let text = fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  const lines = text ? text.split(/\r?\n/) : [];
+  const next = [];
+  let replaced = false;
+  const assignment = `${key}=${String(value)}`;
+  for (const line of lines) {
+    if (line.startsWith(`${key}=`)) {
+      next.push(assignment);
+      replaced = true;
+    } else if (line.length || next.length) {
+      next.push(line);
+    }
+  }
+  if (!replaced) {
+    if (next.length && next[next.length - 1] !== "") next.push("");
+    next.push(assignment);
+  }
+  while (next.length && next[next.length - 1] === "") next.pop();
+  next.push("");
+  fs.writeFileSync(p, next.join("\n"), { mode: 0o600 });
+  try {
+    fs.chmodSync(p, 0o600);
+  } catch {
+    // best effort on platforms that ignore mode
+  }
+  return { path: p, key, set: true };
+}
+
+export function platformStatus(profile = "oracle") {
+  const env = readProfileEnv(profile);
+  const statuses = {};
+  for (const p of listMessagingPlatforms()) {
+    if (!p.required.length) {
+      statuses[p.key] = "manual";
+      continue;
+    }
+    const missing = p.required.filter((k) => !String(env[k] || "").trim());
+    statuses[p.key] = missing.length ? "unset" : "ready";
+  }
+  return { profile, statuses, envPath: profileEnvPath(profile) };
+}
+
+export function renderStatus(profile = "oracle") {
+  const { statuses } = platformStatus(profile);
+  return renderSetupMenu({ profile, statuses });
+}
+
+export function setPlatformToken(profile, platformKey, token, extra = {}) {
+  const platform = findMessagingPlatform(platformKey);
+  if (!platform) {
+    const err = new Error(`unknown platform '${platformKey}'`);
+    err.code = "UNKNOWN_PLATFORM";
+    throw err;
+  }
+  if (!platform.required.length) {
+    const err = new Error(
+      `${platform.key} uses hermes interactive setup (oracle setup messaging)`,
+    );
+    err.code = "NEEDS_INTERACTIVE";
+    throw err;
+  }
+  const primary = platform.required[0];
+  writeProfileEnvKey(profile, primary, token);
+  for (const [k, v] of Object.entries(extra || {})) {
+    if (v != null && String(v).trim()) writeProfileEnvKey(profile, k, v);
+  }
+  return {
+    platform: platform.key,
+    set: platform.required,
+    profile,
+    path: profileEnvPath(profile),
+  };
+}
+
+export function setupStatePath() {
+  return path.join(oracleConfigDir(), "setup-state.json");
+}
+
+export function touchSetupState(patch = {}) {
+  ensureDir(oracleConfigDir());
+  const p = setupStatePath();
+  let cur = {};
+  if (fs.existsSync(p)) {
+    try {
+      cur = JSON.parse(fs.readFileSync(p, "utf8"));
+    } catch {
+      cur = {};
+    }
+  }
+  const next = {
+    ...cur,
+    ...patch,
+    updatedAt: new Date().toISOString(),
+    host: os.hostname(),
+  };
+  fs.writeFileSync(p, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  return next;
+}
+
+export default {
+  profileEnvPath,
+  parseDotEnv,
+  readProfileEnv,
+  writeProfileEnvKey,
+  platformStatus,
+  renderStatus,
+  setPlatformToken,
+  setupStatePath,
+  touchSetupState,
+};

package/src/data/catalog.mjs

@@ -526,3 +526,14 @@ registerProvider({
   baseEnv: ["PARASWAP_API_URL"],
   description: "ParaSwap/Velora public price routes + validated transaction builder",
 });
+
+registerProvider({
+  id: "rfq",
+  venue: "intent-rfq",
+  chainIds: [1, 10, 56, 137, 8453, 42161, 43114],
+  auth: "none",
+  ops: ["health", "intent", "quote"],
+  execution: "prepare",
+  baseEnv: ["ZEROX_API_KEY", "ONEINCH_API_KEY"],
+  description: "Cross-chain RFQ intent normalizer and firm-quote fanout over reviewed venues. Prepares artifacts only, never signs or broadcasts.",
+});

package/src/data/desk-data.mjs

@@ -44,6 +44,7 @@ import * as portfolio from "./providers/portfolio.mjs";
 import * as portfolioHistory from "./providers/portfolio-history.mjs";
 import * as nftPortfolio from "./providers/nft-portfolio.mjs";
 import * as paraswap from "./providers/paraswap.mjs";
+import * as rfq from "./providers/rfq.mjs";
 
 const OPS = {
   "hl-info": {
@@ -356,6 +357,11 @@ const OPS = {
     quote: (o, a = {}) => paraswap.paraswapPrice(a, o),
     prepare: (o, a = {}) => paraswap.paraswapPrepare(a, o),
   },
+  rfq: {
+    health: (o) => rfq.rfqHealth(o),
+    intent: (o, a = {}) => rfq.rfqIntent(a, o),
+    quote: (o, a = {}) => rfq.rfqQuote(a, o),
+  },
 };
 
 /**

package/src/data/providers/rfq.mjs

@@ -0,0 +1,15 @@
+import { normalizeRfqIntent } from "../../rfq/intent.mjs";
+import { requestRfqQuotes } from "../../rfq/sources.mjs";
+
+export function rfqIntent(args = {}, opts = {}) {
+  return normalizeRfqIntent(args, opts);
+}
+
+export async function rfqQuote(args = {}, opts = {}) {
+  const intent = args.intent?.kind === "rfq-intent" ? args.intent : normalizeRfqIntent(args, opts);
+  return requestRfqQuotes(intent, opts);
+}
+
+export async function rfqHealth() {
+  return { ok: true, provider: "rfq", mode: "intent-rfq", execution: "prepare" };
+}

package/src/index.mjs

@@ -38,6 +38,13 @@ export {
 } from "./scanner/index.mjs";
 
 export { bestSwapRoute, bestBridgeRoute, QUALITY } from "./router/index.mjs";
+export {
+  normalizeRfqIntent,
+  normalizeFirmQuote,
+  hashRfqIntent,
+  hashFirmQuote,
+} from "./rfq/intent.mjs";
+export { sourceCandidates, executeRfqCandidates, rankRfqQuotes, requestRfqQuotes } from "./rfq/sources.mjs";
 export { validateNftMintGasWar, assertNftMintGasWar, NftGasWarLimitError } from "./nft-gas-war-guard.mjs";
 export { simulateSell, assertSellable, SELL_SIM } from "./sell-simulation.mjs";
 export { capabilityStatus, assertCapability, autonomousTradingEnabled, posture } from "./capability-posture.mjs";