@oracle-agent/oracle 0.9.7 → 0.10.0

package/src/router/best-execution.mjs

@@ -99,6 +99,111 @@ export function normalizeRoute(raw) {
   };
 }
 
+/**
+ * Measure how badly a route's price decays with size.
+ *
+ * WHY THIS EXISTS: a quote against a drained pool is indistinguishable, in shape,
+ * from a quote against a deep one -- same fields, no error, just a smaller number.
+ * Verified on Robinhood 2026-08-02: a dead Uniswap V3 SQUEEZE pool holding 7.03
+ * USDG happily quoted a 205,374-token sell, and every layer downstream treated
+ * that as truth. `minOut` does NOT protect against this: it guards the price
+ * MOVING between quote and fill, so against a garbage quote it faithfully locks
+ * in the garbage.
+ *
+ * The probe: quote a small slice of the same trade, compare per-unit prices. Real
+ * slippage decays smoothly with size; a drained pool falls off a cliff.
+ *
+ * `probeFn(amountIn) -> amountOut | null`. Returns null when the comparison could
+ * not be made, which callers MUST treat as unproven rather than as a pass.
+ */
+export async function measurePriceImpact(probeFn, amountIn, { divisor = 1000n } = {}) {
+  const full = bn(amountIn);
+  if (full == null || full <= 0n) return null;
+
+  const probeAmt = full / divisor > 0n ? full / divisor : 1n;
+  if (probeAmt >= full) return null; // too small to compare against itself
+
+  let smallOut;
+  let fullOut;
+  try {
+    [smallOut, fullOut] = await Promise.all([probeFn(probeAmt), probeFn(full)]);
+  } catch {
+    return null;
+  }
+
+  const s = bn(smallOut);
+  const f = bn(fullOut);
+  if (s == null || f == null || s <= 0n) return null;
+
+  // Scale to compare per-unit prices without floating point until the last step.
+  const smallPx = Number(s) / Number(probeAmt);
+  const fullPx = Number(f) / Number(full);
+  if (!Number.isFinite(smallPx) || !Number.isFinite(fullPx) || smallPx <= 0) return null;
+
+  return {
+    impactPct: (1 - fullPx / smallPx) * 100,
+    probeAmountIn: probeAmt.toString(),
+    probeAmountOut: s.toString(),
+    fullAmountOut: f.toString(),
+  };
+}
+
+/**
+ * Reject routes whose price impact exceeds a ceiling.
+ *
+ * Applied AFTER ranking so the rejection is visible: a caller can see that the
+ * nominal winner was dropped and why, rather than silently receiving second place.
+ * A route with no impact measurement is NOT dropped here -- absence of evidence is
+ * surfaced through `unmeasured` so the caller decides, but it is never presented
+ * as a passing measurement.
+ */
+export function applyImpactCeiling(ranked, impacts, { maxImpactPct = 25 } = {}) {
+  const rejected = [];
+  const unmeasured = [];
+
+  const kept = (ranked.routes ?? []).filter((r) => {
+    const m = impacts?.[r.source];
+    if (!m) {
+      unmeasured.push(r.source);
+      return true;
+    }
+    if (m.impactPct > maxImpactPct) {
+      rejected.push({
+        source: r.source,
+        impactPct: Number(m.impactPct.toFixed(2)),
+        reason:
+          `price impact ${m.impactPct.toFixed(1)}% exceeds ${maxImpactPct}% ceiling -- ` +
+          "the venue cannot absorb this size near the quoted price",
+      });
+      return false;
+    }
+    return true;
+  });
+
+  const warnings = [...(ranked.warnings ?? [])];
+  if (rejected.length) {
+    warnings.push(
+      `dropped ${rejected.length} route(s) on price impact: ` +
+        rejected.map((r) => `${r.source} (${r.impactPct}%)`).join(", "),
+    );
+  }
+  if (unmeasured.length) {
+    warnings.push(
+      `price impact NOT measured for: ${unmeasured.join(", ")}. These are unproven ` +
+        "against thin liquidity, not proven safe.",
+    );
+  }
+
+  return {
+    ...ranked,
+    routes: kept,
+    best: kept[0] ?? null,
+    impactRejected: rejected,
+    impactUnmeasured: unmeasured,
+    warnings,
+  };
+}
+
 /**
  * Rank normalized routes by NET output.
  *

package/src/router/index.mjs

@@ -5,7 +5,9 @@
 // a one-source "best route" is not a comparison at all, so that case is labelled
 // rather than presented as if it beat something.
 
-import { gatherRoutes, rankRoutes, QUALITY } from "./best-execution.mjs";
+import {
+  gatherRoutes, rankRoutes, QUALITY, measurePriceImpact, applyImpactCeiling,
+} from "./best-execution.mjs";
 import { swapCandidates, bridgeCandidates, nativeUsd } from "./route-sources.mjs";
 import { llamaPrices } from "../data/providers/defillama.mjs";
 
@@ -93,6 +95,45 @@ export async function bestSwapRoute(p, opts = {}) {
     destDecimals: p.decimalsOut ?? dest.decimals,
   });
 
+  // Liquidity check. Ranking alone will happily crown a quote taken against a
+  // drained pool, because a thin venue returns a well-formed number rather than
+  // an error. Re-quote the winner at 1/1000th size and compare per-unit price:
+  // real slippage decays smoothly, a dead pool falls off a cliff.
+  //
+  // Opt out with `maxImpactPct: null` for callers that genuinely want the raw
+  // ranking (analytics, spread display) rather than an executable route.
+  const maxImpactPct = opts.maxImpactPct === undefined ? 25 : opts.maxImpactPct;
+  if (maxImpactPct != null && ranked.best) {
+    const winner = ranked.best.source;
+    const probe = async (amt) => {
+      const sub = swapCandidates({
+        ...p,
+        amountIn: amt.toString(),
+        nativePriceUsd: nativePricePromise,
+        decimalsOut: p.decimalsOut,
+        destDecimalsPromise: destPromise,
+        opts,
+      }).filter((c) => c.source === winner);
+      if (!sub.length) return null;
+      const got = await gatherRoutes(sub, { timeoutMs: opts.timeoutMs ?? 12_000 });
+      return got?.[0]?.amountOut ?? null;
+    };
+
+    const impact = await measurePriceImpact(probe, amountIn);
+    if (impact) {
+      const guarded = applyImpactCeiling(ranked, { [winner]: impact }, { maxImpactPct });
+      return {
+        kind: "swap",
+        chainId,
+        tokenIn,
+        tokenOut,
+        amountIn: String(amountIn),
+        ...guarded,
+        priceImpact: { [winner]: Number(impact.impactPct.toFixed(2)) },
+      };
+    }
+  }
+
   return {
     kind: "swap",
     chainId,

package/src/router/prepare-route.mjs

@@ -196,7 +196,18 @@ export async function prepareBestRoute(p, opts = {}) {
 
   const comparison = await bestSwapRoute(p, opts);
   if (!comparison.best) {
-    return { ok: false, reason: "no source returned a usable route", comparison };
+    // A liquidity rejection is a DIFFERENT failure from "nobody answered", and
+    // conflating them hides the reason a live venue was refused.
+    const blocked = comparison.impactRejected ?? [];
+    return {
+      ok: false,
+      reason: blocked.length
+        ? blocked[0].reason
+        : "no source returned a usable route",
+      priceImpactBlocked: blocked.length > 0,
+      impactRejected: blocked,
+      comparison,
+    };
   }
 
   // Honour an explicit override, but never silently: picking a non-winner is a
@@ -331,6 +342,11 @@ export async function prepareBestRoute(p, opts = {}) {
       grossOut: chosen.grossOut,
       gasUsd: chosen.gasUsd,
     },
+    // Carry the liquidity measurement through to the caller. Without this the
+    // guard runs but its result is invisible, so a consumer cannot tell a route
+    // that PASSED the ceiling from one that was never measured at all.
+    priceImpact: comparison.priceImpact ?? null,
+    impactUnmeasured: comparison.impactUnmeasured ?? [],
     ...prepared,
     unsigned: true,
     signedBy: "user-wallet",

package/src/tui/app.mjs

@@ -371,23 +371,34 @@ export function createOracleTui(options = {}) {
   });
 }
 
-export async function runOracleTui({ hermesPython, args = [], env = process.env, cwd = process.cwd(), stdout = process.stdout, stdin = process.stdin } = {}) {
+export async function runOracleTui({
+  hermesPython,
+  client,
+  tuiFactory = createOracleTui,
+  args = [],
+  env = process.env,
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stdin = process.stdin,
+} = {}) {
   const parsed = parseChatArgs(args);
   if (parsed.query) return { native: false, pass: parsed.pass };
   if (!stdin.isTTY || !stdout.isTTY) return { native: false, pass: parsed.pass };
-  // Native TUI is intentionally opt-in while the stable oracle shim remains pinned.
-  if (env.ORACLE_NATIVE_TUI !== "1") return { native: false, pass: parsed.pass };
+  if (env.ORACLE_NATIVE_TUI === "0") return { native: false, pass: parsed.pass };
   const invocation = hermesPython;
-  if (!invocation) return { native: false, pass: parsed.pass };
+  if (!client && !invocation) return { native: false, pass: parsed.pass };
   const cleanEnv = activeChainEnv({
     ...env,
     ORACLE_CHAT_SURFACE: "1",
     ORACLE_PROFILE: "oracle",
     ORACLE_NODE_BIN: process.execPath,
   });
-  const tui = createOracleTui({
-    python: invocation.command,
-    pythonArgs: invocation.prefix || [],
+  const tui = tuiFactory({
+    ...(client ? { client } : {}),
+    ...(invocation ? {
+      python: invocation.command,
+      pythonArgs: invocation.prefix || [],
+    } : {}),
     cwd,
     env: cleanEnv,
     stdin,

package/src/tui/backend.mjs

@@ -0,0 +1,145 @@
+const PROVIDERS = Object.freeze({
+  openrouter: {
+    key: "OPENROUTER_API_KEY",
+    baseUrl: "https://openrouter.ai/api/v1",
+    model: "openrouter/auto",
+  },
+  openai: {
+    key: "OPENAI_API_KEY",
+    baseUrl: "https://api.openai.com/v1",
+    model: "gpt-4.1-mini",
+  },
+  xai: {
+    key: "XAI_API_KEY",
+    baseUrl: "https://api.x.ai/v1",
+    model: "grok-4-latest",
+  },
+  deepseek: {
+    key: "DEEPSEEK_API_KEY",
+    baseUrl: "https://api.deepseek.com/v1",
+    model: "deepseek-chat",
+  },
+  gemini: {
+    key: "GEMINI_API_KEY",
+    alternateKey: "GOOGLE_API_KEY",
+    baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai",
+    model: "gemini-2.5-flash",
+  },
+});
+
+const OAUTH_PROVIDERS = Object.freeze({
+  "anthropic-oauth": {
+    baseUrl: "https://api.anthropic.com/v1",
+    model: "claude-sonnet-4-6",
+    protocol: "anthropic-messages",
+  },
+  "openai-codex": {
+    baseUrl: "https://chatgpt.com/backend-api/codex",
+    model: "gpt-5.6-sol",
+    protocol: "responses",
+  },
+  "xai-oauth": {
+    baseUrl: "https://api.x.ai/v1",
+    model: "grok-4.5",
+    protocol: "responses",
+  },
+});
+
+function positiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value || ""), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function providerFromEnv(env, stored = {}) {
+  const explicit = String(env.ORACLE_PROVIDER || stored.provider || "").trim().toLowerCase();
+  if (explicit) return explicit;
+  if (env.ORACLE_BASE_URL) return "custom";
+  for (const [name, preset] of Object.entries(PROVIDERS)) {
+    if (env[preset.key] || (preset.alternateKey && env[preset.alternateKey])) return name;
+  }
+  return null;
+}
+
+export function standaloneConfigFromEnv(
+  env = process.env,
+  stored = {},
+  oauthAvailable = () => false,
+  apiKeyResolver = () => "",
+) {
+  const provider = providerFromEnv(env, stored);
+  if (!provider) return null;
+
+  const oauthPreset = OAUTH_PROVIDERS[provider];
+  const preset = PROVIDERS[provider] || oauthPreset;
+  const apiKeyEnv = String(env.ORACLE_API_KEY_ENV || stored.apiKeyEnv || "");
+  const apiKey = String(
+    env.ORACLE_API_KEY ||
+    (apiKeyEnv && env[apiKeyEnv]) ||
+    (preset && (env[preset.key] || (preset.alternateKey && env[preset.alternateKey]))) ||
+    apiKeyResolver(provider) ||
+    "",
+  );
+  const baseUrl = String(
+    oauthPreset
+      ? oauthPreset.baseUrl
+      : provider === "custom"
+        ? (env.ORACLE_BASE_URL || stored.baseUrl || "")
+        : (preset?.baseUrl || ""),
+  ).replace(/\/+$/, "");
+  const model = String(env.ORACLE_MODEL || stored.model || preset?.model || "");
+  if (!baseUrl || !model) return null;
+  const hasOAuth = Boolean(oauthPreset && oauthAvailable(provider));
+  if (oauthPreset && !hasOAuth) return null;
+  if (!oauthPreset && provider !== "custom" && !apiKey) return null;
+
+  return {
+    kind: "standalone",
+    provider,
+    model,
+    baseUrl,
+    ...(hasOAuth ? { authType: "oauth", protocol: oauthPreset.protocol } : { apiKey }),
+    contextLength: positiveInteger(env.ORACLE_CONTEXT_LENGTH || stored.contextLength, 128000),
+    reasoningEffort: String(env.ORACLE_REASONING_EFFORT || stored.reasoningEffort || "high"),
+  };
+}
+
+function setupReason(extra = "") {
+  return [
+    "Oracle standalone chat does not require Hermes.",
+    "Set OPENROUTER_API_KEY, run `oracle auth login claude|codex|grok`, or configure a custom OpenAI-compatible endpoint.",
+    "If Hermes is installed, Oracle will reuse it automatically.",
+    extra,
+  ].filter(Boolean).join("\n");
+}
+
+export function resolveChatBackend({
+  env = process.env,
+  hermes = { ok: false },
+  storedConfig = null,
+  oauthAvailable = () => false,
+  apiKeyResolver = () => "",
+} = {}) {
+  const requested = String(env.ORACLE_CHAT_BACKEND || storedConfig?.backend || "auto").trim().toLowerCase();
+  const standalone = standaloneConfigFromEnv(env, storedConfig || {}, oauthAvailable, apiKeyResolver);
+
+  if (requested === "standalone") {
+    return standalone
+      ? { kind: "standalone", config: standalone }
+      : { kind: "unconfigured", reason: setupReason("ORACLE_CHAT_BACKEND=standalone was requested, but no standalone model is configured.") };
+  }
+
+  if (requested === "hermes") {
+    return hermes?.ok
+      ? { kind: "hermes", bin: hermes.bin }
+      : { kind: "unconfigured", reason: setupReason("ORACLE_CHAT_BACKEND=hermes was requested, but Hermes was not found.") };
+  }
+
+  if (requested !== "auto") {
+    return { kind: "unconfigured", reason: setupReason(`Unknown ORACLE_CHAT_BACKEND value: ${requested}`) };
+  }
+  if (hermes?.ok) return { kind: "hermes", bin: hermes.bin };
+  if (standalone) return { kind: "standalone", config: standalone };
+  return { kind: "unconfigured", reason: setupReason() };
+}
+
+export default { resolveChatBackend, standaloneConfigFromEnv };