@senpi/runtime 3.0.0-dev.runtime-phase-2.20260623210537 → 3.0.0-dev.runtime-phase-2.20260625112547

package/dist/scanners/external/momentum/README.md

@@ -1,148 +0,0 @@
-# External momentum producer
-
-A standalone momentum scanner that runs as an external producer:
-
-1. Pulls instruments + latest candles from the live Senpi MCP server.
-2. Computes last-vs-prev close % move per candidate using a self-contained
-   port of the momentum scanner logic (no dependency on the runtime's internal
-   `momentumScanner`).
-3. Pushes resulting `MOMENTUM_BREAKOUT` signals into a running runtime via the
-   `senpi.ingestExternalScannerData` gateway RPC.
-
-The companion recipe wires those signals into an LLM `OPEN_POSITION` action,
-demonstrating the full e2e path from external signal → LLM gauntlet →
-Senpi MCP position open → DSL trailing-exit management.
-
-## Files
-
-- `momentum.yaml` — runtime recipe declaring the matching `external_scanner`
-  (`external_momentum`), the `momentum_entry` LLM OPEN_POSITION action, and
-  a DSL exit preset tuned for short-horizon momentum trades.
-- `producer.mjs` — the external producer entrypoint.
-
-## Prereqs
-
-1. Build the project so the MCP provider bridge is available:
-   ```bash
-   npm run build
-   ```
-2. Install the runtime from `momentum.yaml` for your strategy wallet and start it:
-   ```bash
-   openclaw senpi runtime create -p src/scanners/external/momentum/momentum.yaml
-   ```
-3. Ensure `openclaw` is on `PATH` and authenticated against the host running
-   that runtime.
-4. Export Senpi MCP credentials and the target wallet:
-   ```bash
-   export SENPI_API_KEY="..."
-   export SENPI_MCP_URL="https://mcp.prod.senpi.ai/mcp"
-   export STRATEGY_ADDRESS="0x..."
-   ```
-
-## Run
-
-```bash
-node src/scanners/external/momentum/producer.mjs
-```
-
-The producer fetches one snapshot (instruments + candles), derives signals,
-and pushes them. It exits non-zero on any rejection or signal-count mismatch.
-Re-run (or wrap in `watch`/cron) for continuous monitoring.
-
-## Schedule with OpenClaw cron
-
-The producer runs **once per invocation** — it fetches a snapshot, pushes
-signals, and exits. For continuous monitoring you need a scheduler. The
-recommended approach is to register an OpenClaw cron immediately after
-creating the runtime strategy, and let your agent wire it up.
-
-Ask your agent something like:
-
-> Set up an OpenClaw cron that runs
-> `src/scanners/external/momentum/producer.mjs` every 5 minutes, with
-> wake now, in an isolated session, and capture output to a dedicated log
-> file named `external_momentum.log` for debugging.
-
-That request maps to these properties on the cron:
-
-- **Command:** `node /absolute/path/to/src/scanners/external/momentum/producer.mjs`
-  (export the same `SENPI_*` and `STRATEGY_ADDRESS` env vars the manual run uses).
-- **Interval:** every X minutes — pick a cadence that matches your
-  `TIMEFRAME` (e.g. `*/5 * * * *` for `1h` candles is plenty; tighten only
-  if you actually need faster reactions).
-- **Wake now:** trigger an immediate first run on creation so you don't
-  wait a full interval to confirm wiring.
-- **Isolated session:** each tick runs in its own session so a hung or
-  long-running invocation can't block the next one.
-- **Log capture:** redirect stdout/stderr to `<scanner-name>.log` (here:
-  `external_momentum.log`) so each run's accept/reject output and any
-  errors are inspectable after the fact.
-
-Verify by tailing the log after the first wake-now tick — you should see
-the same `accepted: true` / `signalCount` payload shown above. If signals
-aren't flowing, check the log first; producer rejections and missing env
-vars surface there.
-
-## Env
-
-| Var | Default | Purpose |
-|---|---|---|
-| `SENPI_API_KEY` | _required_ | Senpi MCP auth |
-| `SENPI_MCP_URL` | _required_ | Senpi MCP endpoint |
-| `STRATEGY_ADDRESS` | _required_ | Target wallet — must match the installed runtime |
-| `EXTERNAL_SCANNER_NAME` | `external_momentum` | Must match `scanners[].name` in the recipe |
-| `OPENCLAW_BIN` | `openclaw` | Path/name of the OpenClaw CLI binary |
-| `TIMEFRAME` | `1h` | Candle interval to evaluate |
-| `MIN_MOVE_PCT` | `1.5` | Minimum absolute % move to emit a signal |
-| `MIN_DAY_VOLUME` | `1000000` | Minimum 24h notional volume to consider an instrument |
-| `MIN_LEVERAGE` | `5` | Minimum max leverage for an instrument |
-| `MAX_CANDIDATES` | `20` | Top-N by volume to fetch candles for |
-| `MIN_SIGNAL_SCORE` | `0.2` | Drop signals below this normalized score |
-
-## Expected response
-
-```json
-{
-  "accepted": true,
-  "address": "0x...",
-  "scanner": "external_momentum",
-  "timestamp": 1775680200000,
-  "signalCount": 3,
-  "contextUpdated": false
-}
-```
-
-## Live test: force an OPEN_POSITION
-
-To verify the end-to-end entry path, loosen thresholds so almost any moving
-asset trips a signal, then let the LLM gauntlet in `momentum.yaml` decide:
-
-```bash
-MIN_MOVE_PCT=0.05 \
-MIN_SIGNAL_SCORE=0 \
-MIN_DAY_VOLUME=0 \
-node src/scanners/external/momentum/producer.mjs
-```
-
-Expect `accepted: true` with `signalCount >= 1`. In the runtime logs you
-should see `momentum_entry` firing, the LLM returning `execute: true` for
-the strongest-scoring eligible signal, and Senpi MCP opening the position.
-The DSL preset in `momentum.yaml` then takes over for trailing-exit
-management. Revert the env values before running unattended.
-
-## Manual e2e checklist
-
-- Happy path: live wallet, no strong movers → producer prints `0` signals
-  and skips the ingest.
-- Triggered path: a high-volume asset with a notable 1h move → producer
-  emits `MOMENTUM_BREAKOUT`; gateway returns `accepted: true` with matching
-  `signalCount`; runtime invokes the LLM action; position opens if the
-  gauntlet passes.
-- DSL handoff: after a fill, confirm `openclaw senpi position list` shows
-  the open position and that the DSL monitor is tracking it.
-- Unknown wallet: change `STRATEGY_ADDRESS` to a wallet without an installed
-  runtime → expect `NOT_FOUND`.
-- Disabled scanner: stop the runtime or rename the scanner in the recipe →
-  expect `INVALID_REQUEST`.
-- Schema rejection: edit `toExternalBatchItem` in `producer.mjs` to drop
-  `sourceMeta` → expect a validation `INVALID_REQUEST`.

package/dist/scanners/external/momentum/momentum.yaml

@@ -1,116 +0,0 @@
-name: external-momentum
-version: 1.0.0
-description: >
-  External producer variant of the momentum scanner. Latest-candle breakout
-  detection runs out-of-process (see producer.mjs) and pushes signals in via
-  senpi.ingestExternalScannerData. An LLM gauntlet filters breakouts into
-  OPEN_POSITION decisions; the DSL exit engine manages trailing exits.
-
-strategy:
-  wallet: "${WALLET_ADDRESS}"
-  budget: 500
-  slots: 2
-  margin_per_slot: 200
-  trading_risk: moderate
-  enabled: true
-
-scanners:
-  # Onchain position tracker — emits position lifecycle events into the DSL
-  # exit engine for trailing stop-loss management.
-  - name: position_tracker
-    type: position_tracker
-    interval: 10s
-
-  # External scanner: signals are pushed by producer.mjs on its own cadence.
-  # `fields` documents the payload shape the gateway will accept.
-  - name: external_momentum
-    type: external_scanner
-    outputs:
-      signals: true
-      context: false
-    config:
-      fields:
-        sourceScannerId: { type: string, required: true }
-        sourceSignalType: { type: string, required: true }
-        sourceTimestamp: { type: number, required: true }
-        sourceFactors: { type: object, required: true }
-        sourceMeta: { type: object, required: true }
-
-actions:
-  # Position lifecycle tracking — feeds DSL exit engine.
-  - name: position_tracker_action
-    action_type: POSITION_TRACKER
-    decision_mode: rule
-    scanners: [position_tracker]
-
-  # Entry: LLM gauntlet on momentum breakout signals.
-  - name: momentum_entry
-    action_type: OPEN_POSITION
-    decision_mode: llm
-    decision_model: gpt-5.1-codex
-    scanners: [external_momentum]
-    min_confidence: 6
-    context:
-      - type: signal
-        scanner: external_momentum
-    decision_prompt: |
-      You are a trade-decisioning evaluator. Given a MOMENTUM_BREAKOUT
-      signal, decide whether to open a position on it or skip.
-
-      A MOMENTUM_BREAKOUT fires when an asset's latest closed candle moves
-      by at least a configured threshold vs. the previous close on the
-      signal's timeframe — i.e. a short-term directional breakout in price.
-      `meta.movePct` carries the signed % change (positive = LONG bias,
-      negative = SHORT bias); `score` (0..1) scales with the move's
-      magnitude; `meta.dayNtlVlm` and `meta.maxLeverage` describe the
-      instrument's liquidity and leverage headroom.
-
-      SIGNAL DATA:
-      {{signal_external_momentum}}
-
-      ═══ GAUNTLET ═══
-      1. movePct magnitude — require |movePct| >= 1.5; reject sub-threshold noise.
-      2. Direction sanity — LONG only if movePct > 0, SHORT only if movePct < 0.
-      3. Liquidity — meta.dayNtlVlm must be >= 1_000_000.
-      4. Leverage — meta.maxLeverage must be >= 5; skip otherwise.
-      5. Score — use the producer score (0..1) as a proxy for strength; require >= 0.4.
-      6. One signal at a time — pick the highest-score eligible signal; skip the rest.
-
-      Respond with a single JSON object:
-      {
-        "execute": true|false,
-        "actionType": "OPEN_POSITION",
-        "confidence": 1-10,
-        "reasoning": "one sentence",
-        "payload": {
-          "signals": [
-            { "asset": "<ticker>", "direction": "LONG"|"SHORT", "reason": "one sentence" }
-          ]
-        }
-      }
-
-# ── EXIT (DSL) ──
-# Trailing stop-loss tuned for short-horizon momentum entries: a slightly
-# tighter Phase-1 fixed floor than Fox (momentum reversals are fast), the same
-# 7% retrace trigger so winners get room to breathe, and a four-tier Phase-2
-# ladder that locks in progressively more of the high-water as gains extend.
-exit:
-  engine: dsl
-  interval_seconds: 30
-  dsl_preset:
-    phase1:
-      enabled: true
-      max_loss_pct: 2.5
-      retrace_threshold: 7
-      consecutive_breaches_required: 3
-    phase2:
-      enabled: true
-      tiers:
-        - { trigger_pct: 6,  lock_hw_pct: 35 }
-        - { trigger_pct: 10, lock_hw_pct: 55 }
-        - { trigger_pct: 15, lock_hw_pct: 70 }
-        - { trigger_pct: 20, lock_hw_pct: 85 }
-
-# ── NOTIFICATIONS ──
-notifications:
-  telegram_chat_id: "${TELEGRAM_CHAT_ID}"

package/dist/scanners/external/momentum/producer.mjs

@@ -1,251 +0,0 @@
-/**
- * External momentum producer.
- *
- * A standalone momentum scanner that:
- *   1. Pulls instruments + latest candles from the live Senpi MCP server.
- *   2. Computes last-vs-prev close % move against configurable thresholds.
- *   3. Pushes MOMENTUM_BREAKOUT signals into a running runtime via the
- *      `openclaw senpi external-scanner ingest` CLI command.
- *
- * Prereqs:
- *   - `npm run build` so dist/ is current (used only for the MCP provider bridge).
- *   - A runtime installed from ./momentum.yaml is running for STRATEGY_ADDRESS.
- *   - `openclaw` CLI on PATH and authenticated against that runtime.
- *   - SENPI_API_KEY and SENPI_MCP_URL env vars set.
- *
- * Run:  node src/scanners/external/momentum/producer.mjs
- */
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { createSenpiScannerProviders } from "../../../../dist/scanners/index.js";
-import { pushScannerSignals } from "../shared/ingest.mjs";
-
-// ─── Config ─────────────────────────────────────────────────────────────────
-
-const SENPI_API_KEY = process.env.SENPI_API_KEY;
-const SENPI_MCP_URL = process.env.SENPI_MCP_URL;
-const STRATEGY_ADDRESS = process.env.STRATEGY_ADDRESS;
-const SCANNER_NAME =
-  process.env.EXTERNAL_SCANNER_NAME ?? "external_momentum";
-const OPENCLAW_BIN = process.env.OPENCLAW_BIN ?? "openclaw";
-const SCANNER_ID = "external-momentum-producer";
-
-const config = {
-  timeframe: process.env.TIMEFRAME ?? "1h",
-  minMovePct: numEnv("MIN_MOVE_PCT", 1.5),
-  minDayVolume: numEnv("MIN_DAY_VOLUME", 1_000_000),
-  minLeverage: numEnv("MIN_LEVERAGE", 5),
-  maxCandidates: numEnv("MAX_CANDIDATES", 20),
-  minSignalScore: numEnv("MIN_SIGNAL_SCORE", 0.2),
-};
-
-if (!SENPI_API_KEY || !SENPI_MCP_URL || !STRATEGY_ADDRESS) {
-  console.error(
-    "Missing required env vars. Set SENPI_API_KEY, SENPI_MCP_URL, and STRATEGY_ADDRESS.\n" +
-      "  export SENPI_API_KEY='...'\n" +
-      "  export SENPI_MCP_URL='https://mcp.prod.senpi.ai/mcp'\n" +
-      "  export STRATEGY_ADDRESS='0x...'",
-  );
-  process.exit(1);
-}
-
-function numEnv(name, fallback) {
-  const raw = process.env[name];
-  if (raw === undefined || raw === "") return fallback;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) {
-    throw new Error(`Env ${name} must be a finite number, got "${raw}"`);
-  }
-  return parsed;
-}
-
-// ─── MCP → SenpiToolClient bridge ───────────────────────────────────────────
-
-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}`);
-      }
-
-      if (result.structuredContent !== undefined) {
-        return result.structuredContent;
-      }
-
-      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;
-    },
-  };
-}
-
-// ─── Momentum logic ─────────────────────────────────────────────────────────
-// Self-contained port of src/scanners/implementations/momentum.ts. Kept free
-// of any runtime-internal imports.
-
-function clamp01(value) {
-  if (!Number.isFinite(value)) return 0;
-  if (value < 0) return 0;
-  if (value > 1) return 1;
-  return value;
-}
-
-function selectCandidates(instruments, cfg) {
-  const eligible = instruments.filter((inst) => {
-    if (inst.isDelisted) return false;
-    if ((inst.maxLeverage ?? 0) < cfg.minLeverage) return false;
-    const vol = inst.context?.dayNtlVlm ?? 0;
-    return vol >= cfg.minDayVolume;
-  });
-  eligible.sort(
-    (a, b) => (b.context?.dayNtlVlm ?? 0) - (a.context?.dayNtlVlm ?? 0),
-  );
-  return eligible.slice(0, cfg.maxCandidates);
-}
-
-function computeMovePct(series) {
-  if (!series || series.length < 2) return null;
-  const prev = series[series.length - 2]?.close;
-  const last = series[series.length - 1]?.close;
-  if (!Number.isFinite(prev) || !Number.isFinite(last) || prev <= 0) {
-    return null;
-  }
-  return { prev, last, movePct: ((last - prev) / prev) * 100 };
-}
-
-function buildSignal({ instrument, move, timeframe, now }) {
-  const movePct = move.movePct;
-  const absMove = Math.abs(movePct);
-  const direction = movePct > 0 ? "LONG" : "SHORT";
-  // Score scales from 0 at minMovePct to 1 at 5% move, clamped.
-  const score = clamp01((absMove - config.minMovePct) / (5 - config.minMovePct));
-
-  return {
-    scannerId: SCANNER_ID,
-    signalType: "MOMENTUM_BREAKOUT",
-    asset: instrument.name,
-    direction,
-    score,
-    timestamp: now,
-    factors: {
-      breakout: true,
-      large_move: absMove >= 3,
-    },
-    meta: {
-      timeframe,
-      movePct,
-      prev: move.prev,
-      last: move.last,
-      dayNtlVlm: instrument.context?.dayNtlVlm ?? 0,
-      maxLeverage: instrument.maxLeverage,
-    },
-  };
-}
-
-// ─── Main ───────────────────────────────────────────────────────────────────
-
-async function main() {
-  console.log(`External momentum producer`);
-  console.log(`  MCP:      ${SENPI_MCP_URL}`);
-  console.log(`  address:  ${STRATEGY_ADDRESS}`);
-  console.log(`  scanner:  ${SCANNER_NAME}`);
-  console.log(`  config:   ${JSON.stringify(config)}`);
-
-  const transport = new StreamableHTTPClientTransport(new URL(SENPI_MCP_URL), {
-    requestInit: { headers: { Authorization: `Bearer ${SENPI_API_KEY}` } },
-  });
-  const mcpClient = new Client({
-    name: "external-momentum",
-    version: "0.0.1",
-  });
-  await mcpClient.connect(transport);
-
-  const providers = createSenpiScannerProviders({
-    client: createSenpiToolClient(mcpClient),
-    logLevel: "warn",
-    cacheTtlMs: { instruments: 0, smData: 0, candles: 0 },
-    candleIntervals: [config.timeframe],
-    maxCandleAssets: config.maxCandidates,
-    retries: 2,
-  });
-
-  try {
-    const instruments = await providers.getInstruments(STRATEGY_ADDRESS);
-    const candidates = selectCandidates(instruments, config);
-    console.log(
-      `\nInstruments: ${instruments.length}, candidates: ${candidates.length}`,
-    );
-
-    if (candidates.length === 0) {
-      console.log("No candidates after filtering — skipping ingest.");
-      return;
-    }
-
-    const candles = await providers.getCandles(STRATEGY_ADDRESS, candidates, {
-      scannerId: SCANNER_ID,
-      preferredAssets: candidates.map((c) => c.name),
-    });
-
-    const now = Date.now();
-    const signals = [];
-    for (const inst of candidates) {
-      const series = candles[inst.name]?.candles?.[config.timeframe];
-      const move = computeMovePct(series);
-      if (!move) continue;
-      if (Math.abs(move.movePct) < config.minMovePct) continue;
-      const signal = buildSignal({
-        instrument: inst,
-        move,
-        timeframe: config.timeframe,
-        now,
-      });
-      if (signal.score < config.minSignalScore) continue;
-      signals.push(signal);
-    }
-
-    console.log(`\nSignals: ${signals.length}`);
-    for (const s of signals) {
-      console.log(
-        `  ${s.asset} ${s.direction} move=${s.meta.movePct.toFixed(2)}% score=${s.score.toFixed(2)}`,
-      );
-    }
-
-    if (signals.length === 0) {
-      console.log("\nNothing to ingest — skipping gateway call.");
-      return;
-    }
-
-    const response = await pushScannerSignals({
-      address: STRATEGY_ADDRESS,
-      scanner: SCANNER_NAME,
-      signals,
-      openclawBin: OPENCLAW_BIN,
-    });
-    console.log("\nIngest response:", JSON.stringify(response));
-  } finally {
-    await transport.close();
-  }
-}
-
-main().catch((error) => {
-  console.error("\nProducer failed:", error.message ?? error);
-  process.exit(1);
-});

package/dist/scanners/external/shared/ingest.mjs

@@ -1,112 +0,0 @@
-/**
- * Shared ingest helpers for external-scanner producers under
- * `src/scanners/external/`.
- *
- * Producers all need the same two things:
- *   1. Normalize an in-producer signal into the external batch item shape
- *      expected by `senpi.ingestExternalScannerData`.
- *   2. Shell out to the openclaw CLI to actually push the batch and parse the
- *      response.
- *
- * Keeping this in one place means producers never diverge on the wire format
- * or response-validation rules, and a future CLI contract change only needs to
- * be made here.
- */
-
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
-
-const execFileAsync = promisify(execFile);
-
-/**
- * Convert a producer-native signal object into the batch item shape consumed
- * by the external-scanner ingest CLI/RPC.
- *
- * Producers emit richer signal objects (scannerId/factors/meta/timestamp) but
- * the runtime only needs the top-level routing fields plus an opaque `data`
- * blob — everything else is preserved under `data.source*` so downstream
- * consumers can reconstruct the original context.
- */
-export function toExternalBatchItem(signal) {
-  return {
-    asset: signal.asset,
-    direction: signal.direction,
-    score: signal.score,
-    signal_type: signal.signalType,
-    data: {
-      sourceScannerId: signal.scannerId,
-      sourceSignalType: signal.signalType,
-      sourceTimestamp: signal.timestamp,
-      sourceFactors: signal.factors,
-      sourceMeta: signal.meta,
-    },
-  };
-}
-
-/**
- * Push a batch of scanner signals from an external producer into a running
- * runtime via the `openclaw senpi external-scanner ingest` CLI command.
- *
- * Named from the producer's point of view: the scanner executing this code
- * is pushing its signals out to the senpi-trading-runtime service.
- *
- * The CLI emits pure JSON on stdout:
- *   - success:  { ok: true, result: { accepted, signalCount, ... } }
- *   - failure:  { ok: false, error: { code, message } }
- *
- * @param {object} opts
- * @param {string} opts.address         Strategy wallet address.
- * @param {string} opts.scanner         Configured external_scanner name.
- * @param {Array<object>} opts.signals  Producer-native signals (will be
- *                                      normalized via `toExternalBatchItem`).
- * @param {string} [opts.openclawBin]   Path or name of the openclaw CLI
- *                                      (defaults to `"openclaw"`).
- * @returns {Promise<object>}           The inner `result` payload from the
- *                                      gateway on success.
- */
-export async function pushScannerSignals({
-  address,
-  scanner,
-  signals,
-  openclawBin = "openclaw",
-}) {
-  const payload = {
-    signals: signals.map(toExternalBatchItem),
-  };
-  const { stdout } = await execFileAsync(openclawBin, [
-    "senpi",
-    "external-scanner",
-    "ingest",
-    "--address",
-    address,
-    "--scanner",
-    scanner,
-    "--payload",
-    JSON.stringify(payload),
-  ]);
-
-  let response;
-  try {
-    response = JSON.parse(stdout);
-  } catch {
-    throw new Error(`CLI returned non-JSON response:\n${stdout}`);
-  }
-
-  if (response?.ok !== true) {
-    const err = response?.error ?? {};
-    const code = err.code ?? "UNKNOWN";
-    const message = err.message ?? JSON.stringify(response);
-    throw new Error(`CLI rejected ingest (${code}): ${message}`);
-  }
-
-  const result = response.result ?? {};
-  if (!result.accepted) {
-    throw new Error(`CLI did not accept ingest: ${JSON.stringify(result)}`);
-  }
-  if (result.signalCount !== signals.length) {
-    throw new Error(
-      `Expected signalCount=${signals.length}, got ${result.signalCount}`,
-    );
-  }
-  return result;
-}