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

package/examples/scanners-liquidation-watchdog.mjs

@@ -1,341 +0,0 @@
-/**
- * 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

@@ -1,208 +0,0 @@
-/**
- * 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);
-});