@oracle-agent/oracle 0.13.1 → 0.14.0

package/bin/oracle-public-server.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Oracle Public HTTP server (Slice G) — secret-free BFF boot script.
+//
+//   ORACLE_PUBLIC_HOST=127.0.0.1 ORACLE_PUBLIC_PORT=8799 node bin/oracle-public-server.mjs
+//
+// Loopback by default. Serves ONLY the public read/assemble contract; no
+// signing, no keys, no executor imports. Every response body is scanned for
+// secret material before send (see src/public-api/http.mjs).
+
+import { startPublicServer, resolvePublicBind, VERSION, PUBLIC_PLANE } from "../src/public-api/http.mjs";
+
+const bind = resolvePublicBind();
+const server = startPublicServer(bind);
+
+server.on("listening", () => {
+  const addr = server.address();
+  const host = typeof addr === "object" && addr ? addr.address : bind.host;
+  const port = typeof addr === "object" && addr ? addr.port : bind.port;
+  // NOTE: log line intentionally carries only public bind info + version.
+  console.log(
+    `oracle-public-server listening on http://${host}:${port} (plane=${PUBLIC_PLANE}, version=${VERSION}, unsigned-only)`
+  );
+});
+
+server.on("error", (err) => {
+  console.error(`oracle-public-server failed to bind: ${err.code || err.message}`);
+  process.exit(1);
+});
+
+for (const sig of ["SIGINT", "SIGTERM"]) {
+  process.on(sig, () => {
+    server.close(() => process.exit(0));
+    // Fallback hard-exit if sockets linger.
+    setTimeout(() => process.exit(0), 1000).unref();
+  });
+}

package/bin/oracle-route.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// oracle-route -- compare swap and bridge routes across every available source.
+//
+// Usage:
+//   oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn]
+//   oracle-route bridge <fromChain> <toChain> <token> [amountIn]
+//
+// <chain> is an id (8453) or key (base). --json for machine output.
+
+import { bestSwapRoute, bestBridgeRoute } from "../src/router/index.mjs";
+import { prepareBestRoute } from "../src/router/prepare-route.mjs";
+import { prepareBestBridgeRoute } from "../src/router/prepare-bridge.mjs";
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const [cmd, ...rest] = process.argv.slice(2);
+const JSON_OUT = rest.includes("--json");
+const args = rest.filter((a) => a !== "--json");
+const NATIVE = "0x0000000000000000000000000000000000000000";
+
+function chainId(ref) {
+  if (!ref) die("missing <chain>");
+  const n = Number(ref);
+  if (getScanner(n)) return n;
+  const s = listScanners().find((x) => x.key === String(ref).toLowerCase());
+  if (s) return s.chainId;
+  die(`unknown chain "${ref}". Known: ${listScanners().map((x) => x.key).join(", ")}`);
+}
+
+function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function fmt(raw, decimals) {
+  const n = Number(raw) / 10 ** decimals;
+  return n.toLocaleString(undefined, { maximumFractionDigits: 6 });
+}
+
+function render(r, decimals) {
+  console.log(`sources: ${r.sourcesAnswered}/${r.sourcesTried} answered`);
+  console.log(`ranked on: ${r.rankedOn}\n`);
+
+  if (!r.routes.length) {
+    console.log("no source returned a usable route.");
+    for (const f of r.failed) console.log(`  ${f.source}: ${f.error}`);
+    return;
+  }
+
+  const w = Math.max(...r.routes.map((x) => x.source.length), 6);
+  console.log(`  ${"source".padEnd(w)}  ${"net out".padStart(14)}  ${"gross".padStart(14)}  cost`);
+  for (const [i, x] of r.routes.entries()) {
+    const mark = i === 0 ? "*" : " ";
+    const cost =
+      x.gasUsd == null
+        ? "gas unknown"
+        : x.gasUsd === 0
+          ? "gasless (solver)"
+          : `$${Number(x.gasUsd + (x.feeUsd ?? 0)).toFixed(2)}`;
+    const dur = x.meta?.durationSeconds != null ? `  ~${x.meta.durationSeconds}s` : "";
+    console.log(
+      `${mark} ${x.source.padEnd(w)}  ${fmt(x.netOut, decimals).padStart(14)}  ` +
+        `${fmt(x.grossOut, decimals).padStart(14)}  ${cost}${dur}`,
+    );
+  }
+
+  for (const f of r.failed) console.log(`  ${f.source.padEnd(w)}  FAILED: ${String(f.error).slice(0, 60)}`);
+
+  console.log(`\n${r.note}`);
+  for (const wn of r.warnings) console.log(`\nWARNING: ${wn}`);
+}
+
+try {
+  switch (cmd) {
+    case "swap": {
+      const cid = chainId(args[0]);
+      if (!args[1] || !args[2]) die("usage: oracle-route swap <chain> <tokenIn> <tokenOut> [amountIn]");
+      const amountIn = args[3] || (10n ** 18n).toString();
+      const scanner = getScanner(cid);
+
+      // Decimals matter twice: ParaSwap needs them to quote at all, and the ranker
+      // needs the destination's to convert gas into output units.
+      const [dIn, dOut] = await Promise.all([
+        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
+        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
+      ]);
+
+      const r = await bestSwapRoute({
+        chainId: cid,
+        tokenIn: args[1],
+        tokenOut: args[2],
+        amountIn,
+        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
+        decimalsIn: dIn,
+        decimalsOut: dOut,
+      });
+      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+      else render(r, dOut ?? 18);
+      break;
+    }
+
+    case "bridge": {
+      const from = chainId(args[0]);
+      const to = chainId(args[1]);
+      const token = args[2] || NATIVE;
+      const amountIn = args[3] || (10n ** 18n).toString();
+
+      const r = await bestBridgeRoute({
+        fromChainId: from,
+        toChainId: to,
+        tokenIn: token,
+        tokenOut: token,
+        amountIn,
+        taker: args[4] || "0x000000000000000000000000000000000000dEaD",
+        decimalsOut: 18,
+      });
+      if (JSON_OUT) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+      else render(r, 18);
+      break;
+    }
+
+    case "prepare": {
+      const cid = chainId(args[0]);
+      if (!args[1] || !args[2] || !args[3]) {
+        die("usage: oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]");
+      }
+      // Argument order puts taker BEFORE amount deliberately: preparing without a
+      // real taker is the one mistake that cannot be recovered from downstream.
+      const taker = args[3];
+      const amountIn = args[4] || (10n ** 18n).toString();
+      const srcArg = rest.find((a) => a.startsWith("--source="));
+      const scanner = getScanner(cid);
+
+      const [dIn, dOut] = await Promise.all([
+        scanner.resolveToken(args[1]).then((t) => t.decimals).catch(() => null),
+        scanner.resolveToken(args[2]).then((t) => t.decimals).catch(() => null),
+      ]);
+
+      const r = await prepareBestRoute({
+        chainId: cid,
+        tokenIn: args[1],
+        tokenOut: args[2],
+        amountIn,
+        taker,
+        decimalsIn: dIn,
+        decimalsOut: dOut,
+        source: srcArg ? srcArg.split("=")[1] : undefined,
+      });
+
+      if (JSON_OUT) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        break;
+      }
+
+      if (!r.ok) {
+        console.log(`could not prepare: ${r.reason}`);
+        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
+        if (r.alternative) console.log(`try: --source=${r.alternative}`);
+        process.exit(1);
+      }
+
+      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
+      console.log(`artifact:    ${r.artifactKind}`);
+      console.log(`destination: ${r.destination}`);
+      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
+      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
+      if (r.requiresApproval) {
+        console.log(`\napproval required first:`);
+        console.log(`  token   ${r.requiresApproval.token}`);
+        console.log(`  spender ${r.requiresApproval.spender}`);
+        if (r.requiresApproval.note) console.log(`  note    ${r.requiresApproval.note}`);
+      }
+      if (r.runnersUp?.length) {
+        console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
+      }
+      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    case "prepare-bridge": {
+      const from = chainId(args[0]);
+      const to = chainId(args[1]);
+      if (!args[2]) die("usage: oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amountIn] [--source=X]");
+      const taker = args[2];
+      const token = args[3] || NATIVE;
+      const amountIn = args[4] || (10n ** 17n).toString();
+      const srcArg = rest.find((a) => a.startsWith("--source="));
+
+      const r = await prepareBestBridgeRoute({
+        fromChainId: from,
+        toChainId: to,
+        tokenIn: token,
+        tokenOut: token,
+        amountIn,
+        taker,
+        decimalsOut: 18,
+        source: srcArg ? srcArg.split("=")[1] : undefined,
+      });
+
+      if (JSON_OUT) {
+        process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+        break;
+      }
+      if (!r.ok) {
+        console.log(`could not prepare: ${r.reason}`);
+        if (r.failureKind) console.log(`kind: ${r.failureKind}`);
+        if (r.alternative) console.log(`try: --source=${r.alternative}`);
+        process.exit(1);
+      }
+
+      console.log(`source:      ${r.chosen.source}${r.chosen.wasWinner ? " (winner)" : " (override -- NOT the winner)"}`);
+      console.log(`artifact:    ${r.artifactKind}`);
+      console.log(`route:       chain ${r.fromChainId} -> chain ${r.toChainId}`);
+      console.log(`signs:       ${r.transactionCount} transaction(s) on chain ${r.fromChainId}`);
+      console.log(`destination: ${r.destination}`);
+      if (r.minOut) console.log(`minOut:      ${r.minOut}`);
+      if (r.durationSeconds != null) console.log(`eta:         ~${r.durationSeconds}s to credit`);
+      if (r.driftBps != null) console.log(`drift:       ${(r.driftBps / 100).toFixed(3)}% vs comparison`);
+      if (r.requiresApproval) {
+        console.log(`\napproval required first:`);
+        console.log(`  token   ${r.requiresApproval.token}`);
+        console.log(`  spender ${r.requiresApproval.spender}`);
+      }
+      r.transactions.forEach((t, i) => {
+        console.log(`\ntx ${i + 1}/${r.transactionCount}: chain ${t.chainId} -> ${t.to}`);
+      });
+      if (r.runnersUp?.length) console.log(`\nrunners-up: ${r.runnersUp.map((x) => x.source).join(", ")}`);
+      for (const w of r.warnings) console.log(`\nWARNING: ${w}`);
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    default:
+      console.log(
+        [
+          "oracle-route -- best-execution routing",
+          "",
+          "  oracle-route swap   <chain> <tokenIn> <tokenOut> [amountIn] [taker]",
+          "  oracle-route bridge <fromChain> <toChain> [token] [amountIn] [taker]",
+          "  oracle-route prepare <chain> <tokenIn> <tokenOut> <taker> [amountIn] [--source=X]",
+          "  oracle-route prepare-bridge <fromChain> <toChain> <taker> [token] [amt] [--source=X]",
+          "",
+          "  Ranks by NET output (gross minus gas and fees), not headline quote.",
+          "  A route quoting more but costing more gas can lose. --json for detail.",
+        ].join("\n"),
+      );
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  die(String(err?.message || err));
+}

package/bin/oracle-scan.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+// oracle-scan -- exercise the chain-scanner framework from the shell.
+//
+// Useful for two things: checking a chain is actually reachable with your RPC
+// config, and researching a token without wiring up an agent first.
+//
+// Usage:
+//   oracle-scan chains                      coverage matrix for every chain
+//   oracle-scan head <chain>                current block
+//   oracle-scan token <chain> <address>     on-chain ERC-20 identity
+//   oracle-scan pools <chain> <address>     tradeable pools by liquidity
+//   oracle-scan risk  <chain> <address>     structural risk checks
+//
+// <chain> is a chain id (8453) or key (base).
+
+import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
+import { getScanner, listScanners, scannerCoverage } from "../src/scanner/contract.mjs";
+
+registerBuiltinScanners();
+
+const [cmd, ...rest] = process.argv.slice(2);
+const JSON_OUT = rest.includes("--json");
+const args = rest.filter((a) => a !== "--json");
+
+function resolve(ref) {
+  if (!ref) die("missing <chain>");
+  const byId = getScanner(Number(ref));
+  if (byId) return byId;
+  const byKey = listScanners().find((s) => s.key === String(ref).toLowerCase());
+  if (byKey) return byKey;
+  die(
+    `unknown chain "${ref}". Known: ${listScanners().map((s) => `${s.key}(${s.chainId})`).join(", ")}`,
+  );
+}
+
+function die(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+
+function out(obj) {
+  process.stdout.write(`${JSON.stringify(obj, null, 2)}\n`);
+}
+
+// A missing RPC is the most common reason a scan fails. Say so precisely instead of
+// surfacing a generic fetch error.
+function rpcHint(scanner, err) {
+  const msg = String(err?.message || err);
+  if (/rpc|fetch|ECONN|timeout|provider/i.test(msg)) {
+    return (
+      `${msg}\n\nThis chain reads its RPC from: ${scanner.rpcEnv.join(" or ")}\n` +
+      `Set one, e.g.:  export ${scanner.rpcEnv[0]}=https://...`
+    );
+  }
+  return msg;
+}
+
+try {
+  switch (cmd) {
+    case "chains": {
+      const cov = scannerCoverage();
+      if (JSON_OUT) {
+        out(cov);
+        break;
+      }
+      console.log(`${cov.chainCount} chains registered\n`);
+      const rows = Object.entries(cov.chains).map(([id, c]) => ({
+        chain: `${c.key} (${id})`,
+        caps: c.supported.length,
+        routing: c.failClosed ? "fail-closed (no verified venue)" : `${c.venueCount} venue(s)`,
+      }));
+      const w = Math.max(...rows.map((r) => r.chain.length));
+      for (const r of rows) {
+        console.log(`  ${r.chain.padEnd(w)}  ${String(r.caps).padStart(2)} caps   ${r.routing}`);
+      }
+      console.log(
+        "\nEvery chain is read/research capable. Routing value requires a verified\n" +
+          "venue -- see CONTRIBUTING.md for the verification rule.",
+      );
+      break;
+    }
+
+    case "head": {
+      const s = resolve(args[0]);
+      out(await s.blockNumber());
+      break;
+    }
+
+    case "token": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan token <chain> <address>");
+      out(await s.resolveToken(args[1]));
+      break;
+    }
+
+    case "pools": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan pools <chain> <address>");
+      const r = await s.resolvePools(args[1]);
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`evidence: ${r.evidence}`);
+      if (r.reason) console.log(`reason:   ${r.reason}`);
+      for (const p of r.pools.slice(0, 10)) {
+        const liq = p.liquidityUsd == null ? "?" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
+        console.log(`  ${p.dex.padEnd(12)} ${liq.padStart(14)}  ${p.pair}`);
+      }
+      if (!r.pools.length) console.log("  (no pools with liquidity found)");
+      break;
+    }
+
+    case "risk": {
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan risk <chain> <address>");
+      const r = await s.scoreRisk(args[1]);
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`verdict: ${r.verdict}\n`);
+      for (const c of r.checks) {
+        console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
+      }
+      console.log(`\n${r.note}`);
+      break;
+    }
+
+    case "quote": {
+      const s = resolve(args[0]);
+      if (!args[1] || !args[2]) die("usage: oracle-scan quote <chain> <tokenIn> <tokenOut> [amountIn]");
+      if (!s.supports("quote")) {
+        die(
+          `${s.key} has no verified router, so quoting stays fail-closed.\n` +
+            "Add a venue with recorded provenance -- see docs/adding-a-chain.md.",
+        );
+      }
+      const amountIn = args[3] || (10n ** 18n).toString();
+      out(await s.quote({ tokenIn: args[1], tokenOut: args[2], amountIn }));
+      break;
+    }
+
+    case "sell": {
+      // The single most valuable check on a low-cap venue: can you get OUT?
+      const s = resolve(args[0]);
+      if (!args[1]) die("usage: oracle-scan sell <chain> <token> [amountIn]");
+      if (!s.supports("sellSimulation")) {
+        die(
+          `${s.key} has no verified router, so sell simulation is unavailable.\n` +
+            "Without it, treat every token on this chain as unproven for exit.",
+        );
+      }
+      const amountIn = args[2] || (10n ** 16n).toString();
+      const r = await s.sellSimulation({ token: args[1], amountIn });
+      if (JSON_OUT) {
+        out(r);
+        break;
+      }
+      console.log(`verdict:   ${r.verdict}`);
+      console.log(`reason:    ${r.reason ?? ""}`);
+      if (r.retentionBps != null) {
+        console.log(`retention: ${(r.retentionBps / 100).toFixed(2)}%`);
+      }
+      if (r.leg) console.log(`failed at: ${r.leg} leg`);
+      if (r.note) console.log(`\n${r.note}`);
+      break;
+    }
+
+    default:
+      console.log(
+        [
+          "oracle-scan -- chain scanner CLI",
+          "",
+          "  oracle-scan chains                              coverage matrix",
+          "  oracle-scan head  <chain>                       current block",
+          "  oracle-scan token <chain> <address>             ERC-20 identity",
+          "  oracle-scan pools <chain> <address>             pools by liquidity",
+          "  oracle-scan risk  <chain> <address>             structural risk checks",
+          "  oracle-scan quote <chain> <tIn> <tOut> [amt]    live exact-input quote",
+          "  oracle-scan sell  <chain> <token> [amt]         round-trip: can you exit?",
+          "",
+          "  <chain> is an id (8453) or key (base).  --json for machine output.",
+          "  quote/sell need a chain with a verified router (see: oracle-scan chains).",
+        ].join("\n"),
+      );
+      process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  const s = args[0] ? (getScanner(Number(args[0])) || listScanners().find((x) => x.key === args[0])) : null;
+  die(s ? rpcHint(s, err) : String(err?.message || err));
+}

package/bin/oracle-upgrade.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { upgradeProfiles } from "../src/profile-upgrade.mjs";
+
+const argv = process.argv.slice(2);
+const value = (flag) => {
+  const index = argv.indexOf(flag);
+  if (index < 0) return null;
+  if (!argv[index + 1] || argv[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
+  return argv[index + 1];
+};
+
+try {
+  const known = new Set(["--apply", "--json", "--only", "--hermes-home", "--package-root", "--control-command"]);
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!known.has(argv[i])) throw new Error(`unknown option: ${argv[i]}`);
+    if (["--only", "--hermes-home", "--package-root", "--control-command"].includes(argv[i])) i += 1;
+  }
+  const packageRoot = path.resolve(value("--package-root") || path.join(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const hermesHome = path.resolve(value("--hermes-home") || process.env.HERMES_HOME || path.join(os.homedir(), ".hermes"));
+  const control = value("--control-command");
+  const result = upgradeProfiles({
+    hermesHome,
+    packageRoot,
+    only: value("--only"),
+    apply: argv.includes("--apply"),
+    controlCommand: control ? control.trim().split(/\s+/) : null,
+  });
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    console.log(`oracle-upgrade ${result.applied ? "applied" : "dry run"}: ${result.profiles.length} profile(s)`);
+    for (const key of ["created", "updated", "unchanged", "backups"]) console.log(`${key}: ${result[key].length}`);
+    if (!result.applied) console.log("Re-run with --apply to make these changes.");
+  }
+} catch (error) {
+  const failure = { ok: false, error: error.message };
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(failure, null, 2)}\n`);
+  else console.error(`oracle-upgrade: ${error.message}`);
+  process.exitCode = 1;
+}

package/bin/oracle.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { run } from "../src/cli/kernel.mjs";
+
+export const COMMANDS = Object.freeze({
+  data: "./desk-server.mjs",
+  public: "./oracle-public-server.mjs",
+  "data-mcp": "./oracle-data-mcp.mjs",
+  init: "./oracle-init.mjs",
+  upgrade: "./oracle-upgrade.mjs",
+  scan: "./oracle-scan.mjs",
+  route: "./oracle-route.mjs",
+  equities: "./oracle-equities.mjs",
+});
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  return run(argv);
+}
+
+if (isMainModule()) {
+  const code = await main();
+  process.exit(typeof code === "number" ? code : 0);
+}