@senpi/runtime 1.0.95-dev.20260408174401

package/dist/utils/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,GAAG,OAAO,CAa7D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEtD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOtD"}

package/dist/utils/response.js

@@ -0,0 +1,44 @@
+/**
+ * Shared response helpers: envelope unwrapping and type coercion.
+ * Used by senpi client, LLM decision, and scanner adapters.
+ */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Unwraps `{ success, data }` envelopes when present.
+ * When inner data is a record, preserves top-level success/error/message on it so callers do not lose them.
+ * Non-envelope payloads are returned unchanged.
+ */
+export function unwrapEnvelope(input) {
+    if (!isRecord(input))
+        return input;
+    const maybeEnvelope = input;
+    if (typeof maybeEnvelope.success !== "boolean" || !("data" in maybeEnvelope)) {
+        return input;
+    }
+    const inner = maybeEnvelope.data;
+    if (!isRecord(inner))
+        return inner;
+    const out = { ...inner };
+    if (typeof maybeEnvelope.error === "string" && !("error" in out))
+        out.error = maybeEnvelope.error;
+    if (typeof maybeEnvelope.message === "string" && !("message" in out))
+        out.message = maybeEnvelope.message;
+    if (!("success" in out))
+        out.success = maybeEnvelope.success;
+    return out;
+}
+export function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+export function asNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+//# sourceMappingURL=response.js.map

package/dist/utils/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/utils/response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAI,KAAc;IAC9C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACnC,MAAM,aAAa,GAAG,KAAgF,CAAC;IACvG,IAAI,OAAO,aAAa,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,IAAI,aAAa,CAAC,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC;IACjC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAU,CAAC;IACxC,MAAM,GAAG,GAAG,EAAE,GAAG,KAAK,EAA6B,CAAC;IACpD,IAAI,OAAO,aAAa,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC;IAClG,IAAI,OAAO,aAAa,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAC1G,IAAI,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC;QAAE,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,OAAO,CAAC;IAC7D,OAAO,GAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACxB,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/retry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Retry helper for external calls (e.g. DSL SenpiClient). No backoff; fixed delay between attempts.
+ */
+export interface RetryOptions {
+    /** Number of retries (total attempts = retries + 1). Default 2. */
+    retries?: number;
+    /** Delay in ms before each retry. Default 500. */
+    delayMs?: number;
+    /** Label for logging (e.g. "editPosition"). */
+    label?: string;
+    /** Optional: called on each retry with (attempt, retriesRemaining, error). */
+    onRetry?: (attempt: number, retriesRemaining: number, error: unknown) => void;
+}
+/**
+ * Executes fn(); on failure waits delayMs then retries up to retries times.
+ * @throws Last error if all attempts fail.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC/E;AAMD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/utils/retry.js

@@ -0,0 +1,32 @@
+/**
+ * Retry helper for external calls (e.g. DSL SenpiClient). No backoff; fixed delay between attempts.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Executes fn(); on failure waits delayMs then retries up to retries times.
+ * @throws Last error if all attempts fail.
+ */
+export async function withRetry(fn, options = {}) {
+    const { retries = 2, delayMs = 500, label = "call", onRetry } = options;
+    let lastError;
+    for (let attempt = 1; attempt <= retries + 1; attempt += 1) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            lastError = e;
+            const retriesRemaining = retries + 1 - attempt;
+            if (retriesRemaining > 0) {
+                onRetry?.(attempt, retriesRemaining, e);
+                await sleep(delayMs);
+            }
+            else {
+                throw e;
+            }
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,UAAwB,EAAE;IAE1B,MAAM,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,GAAG,EAAE,KAAK,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACxE,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;QAC3D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,SAAS,GAAG,CAAC,CAAC;YACd,MAAM,gBAAgB,GAAG,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC;YAC/C,IAAI,gBAAgB,GAAG,CAAC,EAAE,CAAC;gBACzB,OAAO,EAAE,CAAC,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;gBACxC,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,CAAC;YACV,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Plugin semver from the package root `package.json` (same value CI bumps with `openclaw.plugin.json`).
+ * Resolved at module load so logs and `register()` report the installed release, not a stale constant.
+ */
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH,eAAO,MAAM,OAAO,QAA2B,CAAC"}

package/dist/version.js

@@ -0,0 +1,21 @@
+/**
+ * Plugin semver from the package root `package.json` (same value CI bumps with `openclaw.plugin.json`).
+ * Resolved at module load so logs and `register()` report the installed release, not a stale constant.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function readPackageJsonVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(here, "..", "package.json");
+    try {
+        const raw = readFileSync(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === "string" && pkg.version.length > 0 ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "1.0.0";
+    }
+}
+export const VERSION = readPackageJsonVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,SAAS,sBAAsB;IAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA0B,CAAC;QACrD,OAAO,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC3F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC"}

package/examples/.env.example

@@ -0,0 +1,25 @@
+# Environment variables for @senpi-ai/runtime
+# Copy to .env and fill in values.
+
+# Required for live trading
+SENPI_API_KEY=
+
+# Wallet address used in strategy YAML templates (referenced as ${WALLET_ADDRESS})
+WALLET_ADDRESS=
+
+# Optional: directory for DSL position state files
+# Default: ~/.openclaw/senpi-state
+DSL_STATE_DIR=
+
+# Optional: run-dsl-standalone-live simulated lifecycle
+# --flip-after: DSL_NEW_COIN required; DSL_NEW_SZI / DSL_NEW_ENTRY_PX / DSL_NEW_LEVERAGE optional (single asset only).
+#               If size/entry are omitted, values are auto-read from live clearing house at emit time.
+# --increase-after: optional DSL_INCREASE_SZI / DSL_INCREASE_ENTRY_PX / DSL_INCREASE_LEVERAGE;
+#                   if omitted, values are auto-read from live clearing house at emit time.
+#                   Use DSL_INCREASE_ASSET if multiple coins.
+# --decrease-after: optional DSL_DECREASE_SZI / DSL_DECREASE_ENTRY_PX / DSL_DECREASE_LEVERAGE;
+#                   if omitted, values are auto-read from live clearing house at emit time.
+#                   Use DSL_DECREASE_ASSET if multiple coins.
+
+# MCP server URL — only change for non-prod testing
+# SENPI_MCP_URL=https://mcp.prod.senpi.ai/mcp

package/examples/README.md

@@ -0,0 +1,89 @@
+# Scanners Module Examples
+
+These examples are real clients of the standalone scanners module.
+
+If you are integrating the module as a consumer for the first time, start with `scanners-consumer-quickstart.mjs`.
+
+Each example imports from a built `dist/` entrypoint, so build first:
+
+```bash
+npm run build
+```
+
+Run examples:
+
+```bash
+node examples/scanners-single-strategy.mjs
+node examples/scanners-multi-strategy.mjs
+node examples/scanners-scheduled-events.mjs
+node examples/scanners-senpi-provider-client.mjs
+node examples/scanners-consumer-quickstart.mjs
+node examples/scanners-emerging-movers-v4.mjs
+
+# Requires env vars (see below)
+node examples/scanners-live-mcp.mjs
+node examples/scanners-position-tracker-e2e.mjs
+```
+
+What each example demonstrates:
+
+1. `scanners-consumer-quickstart.mjs`
+- Smallest consumer-oriented setup
+- Which imports to use
+- Required `createScannerRuntimeModule(...)` options
+- Manual `runOnce(...)` flow and `querySignals(...)`
+
+2. `scanners-single-strategy.mjs`
+- One strategy with `prescreener`, `oi-tracker`, `momentum`, `emerging-movers`
+- Manual `runOnce` flow and signal query
+
+3. `scanners-multi-strategy.mjs`
+- Two strategies sharing scanner ids
+- Different scanner configs per strategy and isolated outputs
+
+4. `scanners-scheduled-events.mjs`
+- Interval-driven execution with `start()` / `stop()`
+- Pub/sub lifecycle events (`start`, `complete`, `skip`, `error`)
+
+5. `scanners-senpi-provider-client.mjs`
+- Uses `createSenpiScannerProviders(...)` with a **mock** `callTool` client
+- Demonstrates provider wiring for `prescreener`, `momentum`, and `emerging-movers`
+
+6. `scanners-emerging-movers-v4.mjs`
+- Showcases all five v4 signal types: FIRST_JUMP, CONTRIB_EXPLOSION, IMMEDIATE_MOVER, NEW_ENTRY_DEEP, DEEP_CLIMBER
+- Simulates a 50-token SM leaderboard evolving over 4 scans
+- Production-like v4 config with all detection thresholds
+- Prints signals with priority, reasons, factors, and summary breakdown
+
+7. `scanners-live-mcp.mjs`
+- Connects to the **real Senpi MCP server** using `@modelcontextprotocol/sdk`
+- Bridges `Client.callTool` → `SenpiToolClient` interface
+- Runs all four scanners against live market data and prints results
+- Requires env vars:
+  ```bash
+  export SENPI_API_KEY="your-api-key"
+  export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+  ```
+
+8. `scanners-position-tracker-e2e.mjs`
+- Connects to the **real Senpi MCP server** and runs the `position-tracker` scanner
+- Fetches clearing house state for a strategy wallet with open positions
+- Runs 3 iterations: initial scan (POSITION_OPENED deltas), then 2 steady-state heartbeats
+- Prints detailed position snapshots (direction, size, entry, leverage, uPnL, ROE)
+- Requires env vars:
+  ```bash
+  export SENPI_API_KEY="your-api-key"
+  export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
+  # Optional: override default strategy address
+  export STRATEGY_ADDRESS="0x..."
+  ```
+
+## Strategy YAML templates
+
+See [`strategies/`](./strategies/README.md) for production-ready YAML
+configs you can copy, fill in your wallet address, and load directly:
+
+```bash
+openclaw senpi runtime create -p examples/strategies/wolf.yaml
+```
+

package/examples/scanners-consumer-quickstart.mjs

@@ -0,0 +1,134 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  createScannerRuntimeModule,
+  momentumScanner,
+  prescreenerScanner,
+} from "../dist/index.js";
+
+function createInstruments() {
+  return [
+    {
+      name: "BTC",
+      isDelisted: false,
+      maxLeverage: 10,
+      context: {
+        markPx: 105,
+        prevDayPx: 100,
+        midPx: 105,
+        dayNtlVlm: 80_000_000,
+        openInterest: 2_000_000_000,
+        funding: 0.001,
+      },
+    },
+    {
+      name: "ETH",
+      isDelisted: false,
+      maxLeverage: 8,
+      context: {
+        markPx: 101,
+        prevDayPx: 100,
+        midPx: 101,
+        dayNtlVlm: 40_000_000,
+        openInterest: 1_000_000_000,
+        funding: 0.001,
+      },
+    },
+  ];
+}
+
+function createCandles() {
+  return {
+    BTC: {
+      candles: {
+        "1h": [
+          { timestamp: 1, open: 100, high: 102, low: 99, close: 100, volume: 1000 },
+          { timestamp: 2, open: 100, high: 106, low: 100, close: 105, volume: 1400 },
+        ],
+      },
+    },
+    ETH: {
+      candles: {
+        "1h": [
+          { timestamp: 1, open: 100, high: 101, low: 99, close: 100, volume: 900 },
+          { timestamp: 2, open: 100, high: 101, low: 99, close: 100.2, volume: 920 },
+        ],
+      },
+    },
+  };
+}
+
+async function main() {
+  const stateDir = await mkdtemp(join(tmpdir(), "scanners-consumer-quickstart-"));
+
+  // Required pieces:
+  // - stateDir
+  // - at least one strategy
+  // - scanner factories
+  // - provider functions required by those scanners
+  const scannerModule = createScannerRuntimeModule({
+    stateDir,
+    strategies: [
+      {
+        id: "alpha",
+        name: "Alpha",
+        scannerOverrides: {
+          momentum: {
+            config: {
+              timeframe: "1h",
+              minMovePct: 1.5,
+              maxCandidates: 20,
+              minDayVolume: 1_000_000,
+              minSignalScore: 0.2,
+              requirePrescreened: true,
+            },
+          },
+        },
+      },
+    ],
+    scanners: [prescreenerScanner, momentumScanner],
+    providers: {
+      getInstruments: async () => createInstruments(),
+      getCandles: async () => createCandles(),
+    },
+  });
+
+  scannerModule.on("scanner:run:complete", (event) => {
+    console.log(
+      "complete:",
+      event.scannerId,
+      "status=",
+      event.result.status,
+      "signals=",
+      event.result.signals.length,
+    );
+  });
+
+  try {
+    // Manual operation
+    await scannerModule.runOnce("alpha", "prescreener");
+    await scannerModule.runOnce("alpha", "momentum");
+
+    const signals = await scannerModule.querySignals({
+      strategyId: "alpha",
+      scannerId: "momentum",
+      limit: 10,
+    });
+
+    console.log("persisted momentum signals =", signals.length);
+
+    // Scheduled operation is also available:
+    // await scannerModule.start();
+    // ...
+    // await scannerModule.stop();
+  } finally {
+    await scannerModule.stop();
+    await rm(stateDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});