@senpi/runtime 3.0.0-dev.openclaw-upgrade-mai.20260623210452 → 3.0.0-dev.runtime-phase-2.20260623210537

package/examples/scanners-liquidation-watchdog.mjs

@@ -0,0 +1,341 @@
+/**
+ * Liquidation-watchdog scanner e2e examples.
+ *
+ * Run:  node examples/scanners-liquidation-watchdog.mjs
+ *
+ * Two scenarios:
+ *   1. Without DSL states — scanner operates with margin/liq checks only.
+ *   2. With DSL states — scanner enriches liq-distance alerts with DSL floor info.
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  buildCompositionFromScanners,
+  liquidationWatchdogScanner,
+} from "../dist/scanners/index.js";
+import { StateManager } from "../dist/state/index.js";
+
+// ─── Shared fixtures ────────────────────────────────────────────────────────
+
+function makeClearingHouseState({ bufferPct, positions }) {
+  // bufferPct controls how much margin room is left:
+  //   buffer = (withdrawable / accountValue) * 100
+  //   → withdrawable = accountValue * (bufferPct / 100)
+  const accountValue = 10_000;
+  const withdrawable = accountValue * (bufferPct / 100);
+  const totalMarginUsed = accountValue - withdrawable;
+  return {
+    accountValue,
+    withdrawable,
+    totalMarginUsed,
+    totalUnrealizedPnl: 0,
+    totalNtlPos: 0,
+    positions: positions ?? [],
+  };
+}
+
+function makePosition({ asset, direction, markPrice, liqPrice, roe, marginType }) {
+  // Scanner expects StrategyOpenPosition from types/strategy.ts:
+  //   coin, dex, szi, entryPx, leverage, leverageType, unrealizedPnl, marginUsed, liquidationPx, returnOnEquity
+  // szi sign encodes direction: positive = LONG, negative = SHORT
+  // returnOnEquity is a ratio (e.g. 0.05 for 5%), scanner multiplies by 100
+  const dir = direction ?? "LONG";
+  const szi = dir === "SHORT" ? -1 : 1;
+  const entryPx = markPrice * 0.95;
+  const unrealizedPnl = (markPrice - entryPx) * szi;
+  return {
+    coin: asset,
+    dex: "",
+    szi,
+    entryPx,
+    leverage: 5,
+    leverageType: marginType ?? "cross",
+    unrealizedPnl,
+    marginUsed: entryPx / 5,
+    liquidationPx: liqPrice ?? null,
+    returnOnEquity: (roe ?? 5) / 100,
+  };
+}
+
+// ─── Scenario 1: Without DSL states ─────────────────────────────────────────
+
+async function scenarioWithoutDslStates() {
+  console.log("\n=== Scenario 1: Without DSL states ===\n");
+
+  const stateDir = await mkdtemp(join(tmpdir(), "watchdog-no-dsl-"));
+
+  // Two runs: first healthy, second critical
+  let run = 0;
+  const clearingHouseRuns = [
+    // Run 1: healthy — 80% buffer, positions far from liq
+    makeClearingHouseState({
+      bufferPct: 80,
+      positions: [
+        makePosition({ asset: "BTC", markPrice: 60000, liqPrice: 20000, roe: 12 }),
+        makePosition({ asset: "ETH", markPrice: 3000, liqPrice: 1000, roe: 8 }),
+      ],
+    }),
+    // Run 2: critical — 20% buffer, one position with bad ROE and tight liq
+    makeClearingHouseState({
+      bufferPct: 20,
+      positions: [
+        makePosition({ asset: "BTC", markPrice: 60000, liqPrice: 20000, roe: 5 }),
+        makePosition({ asset: "ETH", markPrice: 3000, liqPrice: 2700, roe: -25, marginType: "cross" }),
+      ],
+    }),
+  ];
+
+  const module = createScannerRuntimeModule({
+    stateDir,
+    ...buildCompositionFromScanners([liquidationWatchdogScanner]),
+    strategies: [
+      {
+        id: "wallet-001",
+        name: "Trader-A",
+        scannerOverrides: {
+          "liquidation-watchdog": {
+            config: {
+              bufferWarningPct: 50,
+              bufferCriticalPct: 30,
+              liqDistanceWarningPct: 30,
+              roeDangerPct: -15,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getClearingHouseState: async () => clearingHouseRuns[Math.min(run, clearingHouseRuns.length - 1)],
+      getActivePositions: async () => [],
+      getInstruments: async () => [],
+      // No getDslStatesForStrategy — scanner should handle gracefully
+    },
+  });
+
+  try {
+    // Run 1: healthy
+    run = 0;
+    const result1 = await module.runOnce("wallet-001", "liquidation-watchdog");
+    console.log("Run 1 (healthy):");
+    console.log("  scannedCount:", result1.scannedCount);
+    console.log("  signals:", result1.signals.length);
+    console.log("  summary.marginBuffer:", result1.summary.marginBuffer);
+    console.log("  summary.alertCount:", result1.summary.alertCount);
+    console.log("  summary.consecutiveCleanChecks:", result1.summary.consecutiveCleanChecks);
+    console.assert(result1.signals.length === 0, "Expected 0 signals for healthy state");
+    console.assert(result1.summary.consecutiveCleanChecks === 1, "Expected 1 clean check");
+
+    // Run 2: critical buffer + tight liq + bad ROE
+    run = 1;
+    const result2 = await module.runOnce("wallet-001", "liquidation-watchdog");
+    console.log("\nRun 2 (critical):");
+    console.log("  scannedCount:", result2.scannedCount);
+    console.log("  signals:", result2.signals.length);
+    console.log("  summary.marginBuffer:", result2.summary.marginBuffer);
+    console.log("  summary.alertCount:", result2.summary.alertCount);
+    console.log("  summary.consecutiveCleanChecks:", result2.summary.consecutiveCleanChecks);
+
+    const closeSignals = result2.signals.filter((s) => s.signalType === "WATCHDOG_CLOSE");
+    const alertSignals = result2.signals.filter((s) => s.signalType === "WATCHDOG_ALERT");
+    console.log("  WATCHDOG_CLOSE signals:", closeSignals.length);
+    console.log("  WATCHDOG_ALERT signals:", alertSignals.length);
+
+    if (closeSignals.length > 0) {
+      console.log("  Close target asset:", closeSignals[0].asset, "(lowest ROE)");
+      console.log("  Close meta:", JSON.stringify(closeSignals[0].meta, null, 2));
+    }
+
+    // Verify no alert message contains "DSL floor" since no DSL states were provided
+    const allMessages = alertSignals.map((s) => s.meta.message);
+    const hasDslFloorNote = allMessages.some((m) => typeof m === "string" && m.includes("DSL floor"));
+    console.assert(!hasDslFloorNote, "Expected no DSL floor notes without dslStates provider");
+    console.assert(closeSignals.length >= 1, "Expected at least 1 WATCHDOG_CLOSE signal");
+    console.assert(closeSignals[0]?.asset === "ETH", "Expected ETH (lowest ROE) as close target");
+    console.assert(result2.summary.consecutiveCleanChecks === 0, "Expected 0 clean checks after alert");
+
+    console.log("\n  [PASS] Scenario 1 completed successfully");
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+// ─── Scenario 2: With DSL states from StateManager ──────────────────────────
+
+async function scenarioWithDslStates() {
+  console.log("\n=== Scenario 2: With DSL states from StateManager ===\n");
+
+  const stateDir = await mkdtemp(join(tmpdir(), "watchdog-with-dsl-"));
+
+  // Seed the StateManager with DSL state files (as the DSL plugin would)
+  const stateManager = new StateManager(stateDir);
+
+  const baseDslState = {
+    version: 1,
+    address: "wallet-002",
+    wallet: "wallet-002",
+    dex: "",
+    highWaterPrice: 0,
+    hwTimestamp: new Date().toISOString(),
+    currentBreachCount: 0,
+    currentTierIndex: null,
+    tierFloorPrice: 0,
+    tiers: [],
+    phase1: { retraceThreshold: 5, absoluteFloor: 0, consecutiveBreachesRequired: 3 },
+    phase2: { retraceFromHW: 4, consecutiveBreachesRequired: 2 },
+    phase2TriggerTier: 0,
+    slOrderId: null,
+    lastSyncedFloorPrice: null,
+    slOrderIdUpdatedAt: null,
+    lastSlSyncError: null,
+    pendingClose: false,
+    active: true,
+    createdAt: new Date().toISOString(),
+    lastCheck: new Date().toISOString(),
+    consecutiveFetchFailures: 0,
+    tickCount: 0,
+    peakROE: 0,
+    lastError: null,
+    lastErrorAt: null,
+    closedAt: null,
+    closeReason: null,
+  };
+
+  await stateManager.setDslState("wallet-002", "BTC", "", {
+    ...baseDslState,
+    asset: "BTC",
+    direction: "LONG",
+    entryPrice: 58000,
+    size: 1,
+    leverage: 5,
+    highWaterPrice: 62000,
+    phase: 2,
+    currentTierIndex: 1,
+    tierFloorPrice: 57000,
+    floorPrice: 56500,    // DSL floor for BTC
+    lastPrice: 60000,
+    peakROE: 15,
+    tickCount: 100,
+  });
+
+  await stateManager.setDslState("wallet-002", "SOL", "", {
+    ...baseDslState,
+    asset: "SOL",
+    direction: "LONG",
+    entryPrice: 140,
+    size: 10,
+    leverage: 5,
+    highWaterPrice: 155,
+    phase: 1,
+    tierFloorPrice: 135,
+    floorPrice: 133,      // DSL floor for SOL
+    lastPrice: 150,
+    peakROE: 10,
+    tickCount: 50,
+  });
+
+  // Verify StateManager has the states
+  const loaded = await stateManager.listDslStates("wallet-002");
+  console.log("  StateManager DSL states loaded:", loaded.length);
+  console.assert(loaded.length === 2, "Expected 2 DSL states in StateManager");
+
+  // Critical clearinghouse scenario
+  const clearingHouse = makeClearingHouseState({
+    bufferPct: 25, // CRITICAL
+    positions: [
+      makePosition({ asset: "BTC", markPrice: 60000, liqPrice: 54000, roe: 3 }),  // 10% liq dist
+      makePosition({ asset: "SOL", markPrice: 150, liqPrice: 130, roe: -18 }),     // ~13.3% liq dist
+    ],
+  });
+
+  // Wire getDslStatesForStrategy to read from the StateManager — same as Runtime does
+  const module = createScannerRuntimeModule({
+    stateDir,
+    ...buildCompositionFromScanners([liquidationWatchdogScanner]),
+    strategies: [
+      {
+        id: "wallet-002",
+        name: "Trader-B",
+        scannerOverrides: {
+          "liquidation-watchdog": {
+            config: {
+              bufferWarningPct: 50,
+              bufferCriticalPct: 30,
+              liqDistanceWarningPct: 30,
+              roeDangerPct: -15,
+            },
+          },
+        },
+      },
+    ],
+    providers: {
+      getClearingHouseState: async () => clearingHouse,
+      getActivePositions: async () => [],
+      getInstruments: async () => [],
+      getDslStatesForStrategy: async (address) => stateManager.listDslStates(address),
+    },
+  });
+
+  try {
+    const result = await module.runOnce("wallet-002", "liquidation-watchdog");
+
+    console.log("Run (critical + DSL from StateManager):");
+    console.log("  scannedCount:", result.scannedCount);
+    console.log("  signals:", result.signals.length);
+    console.log("  summary.marginBuffer:", result.summary.marginBuffer);
+    console.log("  summary.alertCount:", result.summary.alertCount);
+
+    const closeSignals = result.signals.filter((s) => s.signalType === "WATCHDOG_CLOSE");
+    const alertSignals = result.signals.filter((s) => s.signalType === "WATCHDOG_ALERT");
+    console.log("  WATCHDOG_CLOSE signals:", closeSignals.length);
+    console.log("  WATCHDOG_ALERT signals:", alertSignals.length);
+
+    if (closeSignals.length > 0) {
+      console.log("  Close target:", closeSignals[0].asset, "ROE:", closeSignals[0].meta.roe);
+    }
+
+    // Check that liq-distance alerts include DSL floor notes from StateManager
+    const liqAlertMessages = alertSignals
+      .filter((s) => typeof s.meta.message === "string" && s.meta.message.includes("Liquidation distance"))
+      .map((s) => s.meta.message);
+
+    console.log("\n  Liquidation distance alert messages:");
+    for (const msg of liqAlertMessages) {
+      console.log("    -", msg);
+    }
+
+    const hasDslFloorNote = liqAlertMessages.some((m) => m.includes("DSL floor"));
+    console.assert(hasDslFloorNote, "Expected at least one liq alert with DSL floor note");
+    console.assert(closeSignals.length >= 1, "Expected WATCHDOG_CLOSE on critical buffer");
+    console.assert(closeSignals[0]?.asset === "SOL", "Expected SOL (lowest ROE -18) as close target");
+
+    // Verify BTC alert includes DSL floor $56500.00 (from StateManager)
+    const btcAlert = liqAlertMessages.find((m) => m.includes("BTC"));
+    console.assert(btcAlert?.includes("DSL floor: $56500.00"), "Expected BTC alert to contain DSL floor $56500.00 from StateManager");
+
+    // Verify SOL alert includes DSL floor $133.00 (from StateManager)
+    const solAlert = liqAlertMessages.find((m) => m.includes("SOL"));
+    console.assert(solAlert?.includes("DSL floor: $133.00"), "Expected SOL alert to contain DSL floor $133.00 from StateManager");
+
+    console.log("\n  [PASS] Scenario 2 completed successfully");
+  } finally {
+    await module.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  await scenarioWithoutDslStates();
+  await scenarioWithDslStates();
+  console.log("\nAll scenarios passed.\n");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/scanners-live-mcp.mjs

@@ -0,0 +1,208 @@
+/**
+ * Live MCP example — connects to the real Senpi MCP server and runs all
+ * four built-in scanners against live market data.
+ *
+ * Requires two environment variables:
+ *
+ *   export SENPI_API_KEY="your-api-key"
+ *   export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+ *   node examples/scanners-live-mcp.mjs
+ */
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import {
+  createScannerRuntimeModule,
+  createSenpiScannerProviders,
+  prescreenerScanner,
+  oiTrackerScanner,
+  momentumScanner,
+  emergingMoversScanner,
+} from "../dist/scanners/index.js";
+
+// ─── Env guard ──────────────────────────────────────────────────────────────
+
+const SENPI_API_KEY = process.env.SENPI_API_KEY;
+const SENPI_MCP_URL = process.env.SENPI_MCP_URL;
+
+if (!SENPI_API_KEY || !SENPI_MCP_URL) {
+  console.error(
+    "Missing required env vars. Set SENPI_API_KEY and SENPI_MCP_URL before running.",
+  );
+  process.exit(1);
+}
+
+// ─── MCP → SenpiToolClient bridge ──────────────────────────────────────────
+
+/**
+ * Wraps the MCP SDK `Client` so it satisfies the `SenpiToolClient` interface
+ * expected by `createSenpiScannerProviders`.
+ *
+ * The MCP `callTool` returns `{ content: [{ type: "text", text: "…" }] }`.
+ * This bridge parses the JSON from the first text content item back into
+ * a plain object.
+ */
+function createSenpiToolClient(mcpClient) {
+  return {
+    async callTool(name, args) {
+      const result = await mcpClient.callTool({ name, arguments: args });
+
+      if (result.isError) {
+        const errorText =
+          Array.isArray(result.content) &&
+          result.content.length > 0 &&
+          result.content[0].type === "text"
+            ? result.content[0].text
+            : JSON.stringify(result.content);
+        throw new Error(`MCP tool "${name}" returned error: ${errorText}`);
+      }
+
+      // Prefer structuredContent when available.
+      if (result.structuredContent !== undefined) {
+        return result.structuredContent;
+      }
+
+      // Fall back to parsing the first text content item.
+      if (Array.isArray(result.content) && result.content.length > 0) {
+        const first = result.content[0];
+        if (first.type === "text") {
+          try {
+            return JSON.parse(first.text);
+          } catch {
+            return first.text;
+          }
+        }
+      }
+
+      return result.content;
+    },
+  };
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  // 1. Connect to the Senpi MCP server.
+  console.log("Connecting to", SENPI_MCP_URL, "...");
+  const transport = new StreamableHTTPClientTransport(new URL(SENPI_MCP_URL), {
+    requestInit: {
+      headers: { Authorization: `Bearer ${SENPI_API_KEY}` },
+    },
+  });
+  const mcpClient = new Client({ name: "scanners-live-mcp", version: "0.0.1" });
+  await mcpClient.connect(transport);
+  console.log("Connected.\n");
+
+  // 2. Wire up scanner providers backed by the real MCP client.
+  const providers = createSenpiScannerProviders({
+    client: createSenpiToolClient(mcpClient),
+    logLevel: "info",
+    maxCandleAssets: 5,
+    candleIntervals: ["1h"],
+    cacheTtlMs: { instruments: 0, smData: 0, candles: 0 },
+    timeouts: {
+      marketListInstruments: 30_000,
+      marketGetAssetData: 30_000,
+      leaderboardGetMarkets: 30_000,
+    },
+    retries: 2,
+  });
+
+  // 3. Create the runtime module.
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-live-mcp-"));
+  const mod = createScannerRuntimeModule({
+    stateDir,
+    scanners: [prescreenerScanner, oiTrackerScanner, momentumScanner, emergingMoversScanner],
+    strategies: [
+      {
+        id: "live-demo",
+        name: "Live Demo",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 0.5,
+              maxCandidates: 5,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.1,
+              requirePrescreened: true,
+            },
+          },
+          "emerging-movers": {
+            config: {
+              topN: 10,
+              minRankJump: 1,
+              minTopTradersGain: 0.05,
+              minScansBeforeSignals: 2,
+              historyLimit: 30,
+            },
+          },
+        },
+      },
+    ],
+    providers,
+  });
+
+  try {
+    // 4. Run scanners in order.
+    console.log("── prescreener ──");
+    const prescreener = await mod.runOnce("live-demo", "prescreener");
+    console.log("  status:", prescreener.status);
+    console.log("  scanned:", prescreener.scannedCount);
+    console.log("  summary:", prescreener.summary);
+    console.log();
+
+    console.log("── oi-tracker ──");
+    const oiTracker = await mod.runOnce("live-demo", "oi-tracker");
+    console.log("  status:", oiTracker.status);
+    console.log("  scanned:", oiTracker.scannedCount);
+    console.log("  summary:", oiTracker.summary);
+    console.log();
+
+    console.log("── momentum ──");
+    const momentum = await mod.runOnce("live-demo", "momentum");
+    console.log("  status:", momentum.status);
+    console.log("  scanned:", momentum.scannedCount);
+    console.log("  signals:", momentum.signals.length);
+    for (const sig of momentum.signals) {
+      console.log(`    ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}  change=${sig.meta.changePct}%`);
+    }
+    console.log();
+
+    console.log("── emerging-movers (run 1 — warmup) ──");
+    const em1 = await mod.runOnce("live-demo", "emerging-movers");
+    console.log("  status:", em1.status);
+    console.log("  scanned:", em1.scannedCount);
+    console.log();
+
+    console.log("── emerging-movers (run 2 — can signal) ──");
+    const em2 = await mod.runOnce("live-demo", "emerging-movers");
+    console.log("  status:", em2.status);
+    console.log("  scanned:", em2.scannedCount);
+    console.log("  signals:", em2.signals.length);
+    for (const sig of em2.signals) {
+      console.log(`    ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}  jump=${sig.meta.jump}`);
+    }
+    console.log();
+
+    // 5. Query persisted signals across all scanners.
+    const allSignals = await mod.querySignals({ strategyId: "live-demo" });
+    console.log("── querySignals ──");
+    console.log("  total persisted:", allSignals.length);
+    for (const sig of allSignals) {
+      console.log(`    [${sig.scannerId}] ${sig.direction} ${sig.asset}  score=${sig.score.toFixed(2)}`);
+    }
+  } finally {
+    await mod.stop();
+    await transport.close();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});