@oracle-agent/oracle 0.9.6 → 0.9.8

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

@@ -0,0 +1,427 @@
+import { EventEmitter } from "node:events";
+import { activeChainEnv } from "../cli/chain-state.mjs";
+import { createGatewayClient } from "./gateway-client.mjs";
+import { createInput } from "./input.mjs";
+import { createRenderer } from "./renderer.mjs";
+import {
+  formatElapsed,
+  renderBanner,
+  renderBox,
+  renderStatusBar,
+  visibleWidth,
+  wrapText,
+} from "./format.mjs";
+import { createPalette, THEME } from "./theme.mjs";
+
+const LIVE_TAIL_LINES = 6;
+
+function parseChatArgs(args = []) {
+  const out = { pass: [], query: null, model: null, provider: null, quiet: false, cont: false };
+  for (let i = 0; i < args.length; i += 1) {
+    const a = args[i];
+    if ((a === "-q" || a === "--query") && args[i + 1]) {
+      out.query = args[++i];
+      out.pass.push("-q", out.query);
+      continue;
+    }
+    if ((a === "--model" || a === "-m") && args[i + 1]) {
+      out.model = args[++i];
+      out.pass.push("--model", out.model);
+      continue;
+    }
+    if (a === "--provider" && args[i + 1]) {
+      out.provider = args[++i];
+      out.pass.push("--provider", out.provider);
+      continue;
+    }
+    if (a === "--quiet" || a === "-Q") {
+      out.quiet = true;
+      out.pass.push(a);
+      continue;
+    }
+    if (a === "--continue" || a === "-c") {
+      out.cont = true;
+      out.pass.push("--continue");
+      continue;
+    }
+    out.pass.push(a);
+  }
+  return out;
+}
+
+export function applyUsage(state, usage) {
+  if (!usage || typeof usage !== "object") return;
+  const used = Number(usage.context_used ?? usage.context_tokens ?? usage.input ?? usage.prompt);
+  const max = Number(usage.context_max ?? usage.context_length);
+  if (Number.isFinite(used) && used > 0) state.contextTokens = used;
+  if (Number.isFinite(max) && max > 0) state.contextLength = max;
+  const percent = Number(usage.context_percent);
+  if (Number.isFinite(percent)) state.contextPercent = percent;
+  else if (state.contextLength > 0) {
+    state.contextPercent = Math.round((state.contextTokens / state.contextLength) * 100);
+  }
+}
+
+export function composerLines(state) {
+  const width = state.width;
+  const label = `${state.promptLabel} `;
+  const room = Math.max(1, width - 2 - visibleWidth(label));
+  const buffer = state.buffer || "";
+  const cursor = Math.max(0, Math.min(state.cursor ?? buffer.length, buffer.length));
+  let start = 0;
+  if (cursor > room) start = cursor - room;
+  const view = buffer.slice(start, start + room);
+  const rel = cursor - start;
+  const head = view.slice(0, rel);
+  const at = view.slice(rel, rel + 1) || " ";
+  const tail = view.slice(rel + 1);
+  const palette = state.palette;
+  const painted = `${palette.fg(THEME.accent, label)}${head}${palette.bg(THEME.selection_bg, at)}${tail}`;
+  return [painted];
+}
+
+export function fixedLines(state) {
+  const width = state.width;
+  const out = [];
+
+  if (state.liveLines.length > 0) {
+    for (const line of state.liveLines.slice(-LIVE_TAIL_LINES)) out.push(line);
+    out.push("");
+  }
+
+  out.push(...renderBox({
+    lines: composerLines(state),
+    width,
+    palette: state.palette,
+    title: "Ask Oracle ›",
+  }));
+
+  out.push(renderStatusBar({
+    model: state.model,
+    contextTokens: state.contextTokens,
+    contextLength: state.contextLength,
+    percent: state.contextPercent,
+    effort: state.effort,
+    thinking: state.thinking,
+    chain: state.chain,
+    width,
+    palette: state.palette,
+  }));
+  return out;
+}
+
+function eventShape(frame) {
+  const params = frame?.params || frame || {};
+  return {
+    type: params.type || frame?.type || "",
+    sessionId: params.session_id || frame?.session_id || "",
+    payload: params.payload || frame?.payload || {},
+  };
+}
+
+function textPayload(payload = {}) {
+  if (typeof payload.text === "string") return payload.text;
+  if (typeof payload.rendered === "string") return payload.rendered;
+  if (typeof payload.message === "string") return payload.message;
+  return "";
+}
+
+export function createOracleTui(options = {}) {
+  const stdout = options.stdout || process.stdout;
+  const stdin = options.stdin || process.stdin;
+  const width = Math.max(20, Number(stdout.columns || options.columns || 80));
+  const palette = options.palette || createPalette({ color: stdout.isTTY !== false });
+  const renderer = options.renderer || createRenderer({ stdout, rows: stdout.rows, columns: width });
+  const client = options.client || createGatewayClient({
+    python: options.python,
+    pythonArgs: options.pythonArgs || [],
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env,
+    spawnFn: options.spawnFn,
+    startupTimeoutMs: options.startupTimeoutMs,
+    requestTimeoutMs: options.requestTimeoutMs,
+  });
+  const emitter = new EventEmitter();
+  const now = options.now || (() => Date.now());
+  const state = {
+    palette,
+    width,
+    promptLabel: "oracle ›",
+    buffer: "",
+    cursor: 0,
+    model: options.model || "model",
+    contextTokens: 0,
+    contextLength: 0,
+    contextPercent: 0,
+    effort: options.effort || "",
+    thinking: "0s",
+    chain: (options.env || process.env).ORACLE_ACTIVE_CHAIN || "",
+    busy: false,
+    cancelled: false,
+    sessionId: null,
+    assistantBuffer: "",
+    flushedLines: 0,
+    liveLines: [],
+    startedAt: 0,
+  };
+  let input = null;
+  let ticker = null;
+
+  const ui = { renderer, state };
+
+  function renderNow() {
+    renderer.render(fixedLines(state));
+  }
+
+  function emitLine(text) {
+    renderer.writeAbove(`${text}\n`);
+  }
+
+  function recomputeLive() {
+    const parts = state.assistantBuffer.split("\n");
+    const partial = parts[parts.length - 1] || "";
+    state.liveLines = partial ? wrapText(partial, state.width) : [];
+  }
+
+  function flushAssistant({ final = false } = {}) {
+    const parts = state.assistantBuffer.split("\n");
+    const ready = final ? parts.length : parts.length - 1;
+    let wrote = false;
+    while (state.flushedLines < ready) {
+      const line = parts[state.flushedLines];
+      for (const wrapped of wrapText(line, state.width)) emitLine(wrapped);
+      state.flushedLines += 1;
+      wrote = true;
+    }
+    if (final) state.liveLines = [];
+    else recomputeLive();
+    return wrote;
+  }
+
+  function startTicker() {
+    if (ticker) return;
+    ticker = setInterval(() => {
+      if (!state.busy) return;
+      state.thinking = formatElapsed(now() - state.startedAt);
+      renderNow();
+    }, 250);
+    if (typeof ticker.unref === "function") ticker.unref();
+  }
+
+  function stopTicker() {
+    if (!ticker) return;
+    clearInterval(ticker);
+    ticker = null;
+  }
+
+  async function submit(text) {
+    const value = String(text || "").trim();
+    if (!value) return;
+    if (value === "/exit" || value === "/quit") {
+      await stop();
+      return;
+    }
+    if (value === "/clear") {
+      renderer.clear();
+      for (const line of renderBanner({ width: state.width, palette })) emitLine(line);
+      renderNow();
+      return;
+    }
+    state.busy = true;
+    state.assistantBuffer = "";
+    state.flushedLines = 0;
+    state.liveLines = [];
+    state.startedAt = now();
+    state.thinking = "0s";
+    emitLine(`${palette.bold(palette.fg(THEME.prompt, "you"))}  ${value}`);
+    emitLine("");
+    startTicker();
+    renderNow();
+    await client.request("prompt.submit", { session_id: state.sessionId, text: value });
+  }
+
+  function handleEvent(frame) {
+    const event = eventShape(frame);
+    if (event.type === "gateway.ready") return;
+
+    if (event.type === "session.info" && event.payload) {
+      if (event.payload.model) state.model = event.payload.model;
+      if (event.payload.reasoning_effort) state.effort = event.payload.reasoning_effort;
+      applyUsage(state, event.payload.usage);
+      renderNow();
+      return;
+    }
+    if (event.type === "message.start") {
+      state.busy = true;
+      state.cancelled = false;
+      state.assistantBuffer = "";
+      state.flushedLines = 0;
+      state.liveLines = [];
+      emitLine(palette.bold(palette.fg(THEME.accent, "oracle")));
+      renderNow();
+      return;
+    }
+    if (event.type === "thinking.delta" || event.type === "reasoning.delta") {
+      if (state.cancelled) return;
+      const text = textPayload(event.payload).trim();
+      if (text) state.thinking = `${formatElapsed(now() - state.startedAt)}`;
+      renderNow();
+      return;
+    }
+    if (event.type === "message.delta") {
+      if (state.cancelled) return;
+      state.assistantBuffer += textPayload(event.payload);
+      flushAssistant();
+      renderNow();
+      return;
+    }
+    if (event.type === "message.complete") {
+      if (state.cancelled) {
+        state.cancelled = false;
+        return;
+      }
+      const finalText = textPayload(event.payload);
+      if (finalText && finalText.length >= state.assistantBuffer.length) {
+        state.assistantBuffer = finalText;
+      }
+      flushAssistant({ final: true });
+      emitLine("");
+      state.busy = false;
+      stopTicker();
+      applyUsage(state, event.payload?.usage || event.payload?.context);
+      state.thinking = formatElapsed(now() - state.startedAt);
+      renderNow();
+      return;
+    }
+    if (event.type === "error") {
+      state.busy = false;
+      stopTicker();
+      emitLine(palette.fg(THEME.error, `error: ${textPayload(event.payload) || "unknown"}`));
+      renderNow();
+    }
+  }
+
+  async function start() {
+    await client.start();
+    client.on("event", handleEvent);
+    client.on("log", (line) => emitter.emit("log", line));
+    client.on("error", (error) => emitter.emit("error", error));
+    const session = await client.request("session.create", {
+      cols: state.width,
+      cwd: options.cwd || process.cwd(),
+      source: "cli",
+      profile: options.profile || "oracle",
+      close_on_disconnect: true,
+      ...(options.model ? { model: options.model } : {}),
+      ...(options.provider ? { provider: options.provider } : {}),
+    });
+    state.sessionId = session.session_id;
+    state.model = session.info?.model || state.model;
+    if (session.info?.reasoning_effort) state.effort = session.info.reasoning_effort;
+    applyUsage(state, session.info?.usage);
+    for (const line of renderBanner({ width: state.width, palette })) emitLine(line);
+    emitLine("");
+    renderNow();
+    input = createInput({
+      stdin,
+      stdout,
+      onSubmit: (value) => { submit(value).catch((error) => emitter.emit("error", error)); },
+      onCancel: () => {
+        if (!state.busy) return;
+        state.busy = false;
+        state.cancelled = true;
+        stopTicker();
+        flushAssistant({ final: true });
+        emitLine(palette.fg(THEME.warn, "interrupted"));
+        emitLine("");
+        renderNow();
+        client.request("session.interrupt", { session_id: state.sessionId })
+          .catch((error) => emitter.emit("error", error));
+      },
+      onEof: () => { stop().catch((error) => emitter.emit("error", error)); },
+      onClear: () => {
+        renderer.clear();
+        renderNow();
+      },
+      onRender: (editorState) => {
+        state.buffer = editorState.buffer || "";
+        state.cursor = editorState.cursor ?? state.buffer.length;
+        renderNow();
+      },
+    });
+    input.start();
+  }
+
+  async function stop() {
+    stopTicker();
+    if (input) input.stop();
+    renderer.dispose();
+    await client.stop();
+    emitter.emit("stop");
+  }
+
+  return Object.freeze({
+    start,
+    stop,
+    on: emitter.on.bind(emitter),
+    off: emitter.off.bind(emitter),
+    state,
+    handleEvent,
+    submit,
+  });
+}
+
+export async function runOracleTui({ hermesPython, 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 };
+  const invocation = hermesPython;
+  if (!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 || [],
+    cwd,
+    env: cleanEnv,
+    stdin,
+    stdout,
+    model: parsed.model,
+    provider: parsed.provider,
+    profile: "oracle",
+  });
+  tui.on("log", (line) => {
+    if (env.ORACLE_CLI_DEBUG) process.stderr.write(`${line}\n`);
+  });
+  tui.on("error", (error) => {
+    process.stderr.write(`oracle chat: ${error.message}\n`);
+  });
+  await tui.start();
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = async () => {
+      if (done) return;
+      done = true;
+      await tui.stop();
+      resolve({ native: true, code: 0 });
+    };
+    tui.on("stop", () => {
+      if (done) return;
+      done = true;
+      resolve({ native: true, code: 0 });
+    });
+    process.once("SIGINT", finish);
+    process.once("SIGTERM", finish);
+  });
+}
+
+export default {
+  createOracleTui,
+  runOracleTui,
+};