@senpi/trading-recipe 1.0.21

package/dist/actions/types.d.ts

@@ -0,0 +1,123 @@
+export type { HookEventType, HookEvent, HookSystem } from '../types/hooks.js';
+export type { NotificationService } from '../types/notification.js';
+export type { StrategyConfig, } from '../types/strategy.js';
+export type { StateManager, GateCheckResult, RiskGuard, } from '../types/action.js';
+export type { Signal, ScanResult } from '../types/scanner.js';
+export { ScanStatus } from '../types/scanner.js';
+import type { Signal, ScanResult } from '../types/scanner.js';
+/** Per-strategy slot counts for action payload. */
+export interface StrategySlots {
+    total: number;
+    used: number;
+    available: number;
+}
+/** Action-specific enrichment wrapper around a scanner ScanResult. */
+export interface ActionScanPayload {
+    scanResult: ScanResult;
+    /** Sorted signals (e.g. scanResult.signals) for actions to consider. */
+    topPicks?: Signal[];
+    /** Per-strategy total/used/available slots. Keys are addresses. */
+    strategySlots?: Record<string, StrategySlots>;
+    /** True when the emitting strategy (or any, if no address filter) has available slots. */
+    anySlotsAvailable?: boolean;
+    /** Sum of available slots (for emitting strategy when address set, else all). */
+    totalAvailableSlots?: number;
+    /** Number of scans in history (optional). */
+    scansInHistory?: number;
+}
+export interface LlmDecisionRequest {
+    prompt: string;
+    context: Record<string, unknown>;
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+export interface LlmDecisionResponse<T = unknown> {
+    decision: T;
+    rawResponse: string;
+    tokensUsed: number;
+    latencyMs: number;
+}
+export interface LlmDecision {
+    decide<T>(request: LlmDecisionRequest): Promise<LlmDecisionResponse<T>>;
+}
+import type { HookEvent, HookSystem } from '../types/hooks.js';
+import type { NotificationService } from '../types/notification.js';
+import type { StrategyConfig } from '../types/strategy.js';
+import type { RuntimeContext } from '../types/runtime.js';
+import type { RiskGuard, StateManager } from '../types/action.js';
+import type { SenpiClient } from '../senpi/client.js';
+import type { ContextBuilder } from '../context/types.js';
+export type ActionType = 'OPEN_POSITION' | 'CLOSE_POSITION' | 'EMERGENCY_CLOSE_ALL' | string;
+export type DecisionMode = 'llm' | 'script' | 'agent' | 'rule' | 'none';
+export interface ActionConfig {
+    name: string;
+    action_type: ActionType;
+    decision_mode: DecisionMode;
+    decision_model?: string;
+    scanners?: string[];
+    min_confidence?: number;
+    context?: import('../context/types.js').ContextEntry[];
+    decision_prompt?: string;
+    params?: Record<string, unknown>;
+}
+export interface ActionContext {
+    senpi: SenpiClient;
+    stateManager: StateManager;
+    hookSystem: HookSystem;
+    llmDecision: LlmDecision;
+    contextBuilder: ContextBuilder;
+    riskGuard: RiskGuard;
+    notifications: NotificationService;
+    strategies: Map<string, StrategyConfig>;
+    playbook: {
+        tradingStrategyName: string;
+        version: string;
+    };
+    maxLeverageData: Record<string, number>;
+}
+/**
+ * Base decision output from the decision layer.
+ * Enforced fields are common to ALL actions.
+ * Action-specific fields go in `payload` — each action defines its own shape.
+ */
+export interface ActionDecision {
+    execute: boolean;
+    actionType: ActionType;
+    confidence: number;
+    reasoning: string;
+    payload: Record<string, unknown>;
+}
+export interface ActionResult {
+    success: boolean;
+    action_type: ActionType;
+    summary: string;
+    data?: Record<string, unknown>;
+    skipped?: boolean;
+    skipReason?: string;
+    error?: string;
+}
+/**
+ * Core Action contract. Every action implementation must satisfy this.
+ *
+ * Actions are event-driven: instantiated once, receive events via handle(),
+ * return results. They do NOT subscribe themselves to events — the orchestrator
+ * (future) handles wiring.
+ *
+ * Lifecycle: create (factory) -> start() -> handle() [repeated] -> stop()
+ */
+export interface Action {
+    readonly name: string;
+    readonly actionType: ActionType;
+    handle(event: HookEvent): Promise<ActionResult>;
+}
+export type ActionFactory = (config: ActionConfig, context: RuntimeContext) => Action;
+export interface ActionManifest {
+    type: string;
+    name: string;
+    description?: string;
+    eventsConsumed: string[];
+    eventsEmitted: string[];
+    configSchema?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/actions/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":"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"}

package/dist/actions/types.js

@@ -0,0 +1,3 @@
+// ─── Re-export shared types used by the action system ───────────────────────
+export { ScanStatus } from '../types/scanner.js';
+//# sourceMappingURL=types.js.map

package/dist/actions/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/actions/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAgB/E,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/cli/guide-commands.d.ts

@@ -0,0 +1,26 @@
+/**
+ * senpi guide subcommands — in-shell reference for @senpi/trading-recipe.
+ *
+ * All reference text is static string constants. This is intentional: the
+ * scanner registry does not expose configSchema or description metadata at
+ * runtime (ScannerEngine.list() only returns id/enabled/intervalSeconds).
+ *
+ * TODO: replace static strings with dynamic registry metadata once
+ * ScannerEngine exposes configSchema per scanner type. Relevant type is
+ * ScannerRegistrationSummary in src/scanners/engine/engine.ts.
+ */
+/** Minimal Commander command type — mirrors the interface in senpi-commands.ts */
+interface CommanderCommand {
+    command(name: string, desc?: string): CommanderCommand;
+    description(desc: string): CommanderCommand;
+    option(flags: string, description?: string): CommanderCommand;
+    action(fn: (opts?: Record<string, unknown>) => void | Promise<void>): CommanderCommand;
+}
+/**
+ * Register `senpi guide [subcommand]` on the senpi Commander subprogram.
+ * @param senpi  - the `senpi` Commander command object
+ * @param version - plugin version string (from src/version.ts)
+ */
+export declare function registerGuideCommands(senpi: CommanderCommand, version: string): void;
+export {};
+//# sourceMappingURL=guide-commands.d.ts.map

package/dist/cli/guide-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-commands.d.ts","sourceRoot":"","sources":["../../src/cli/guide-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAgTH,kFAAkF;AAClF,UAAU,gBAAgB;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC9D,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;CACxF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,MAAM,GACd,IAAI,CA2CN"}

package/dist/cli/guide-commands.js

@@ -0,0 +1,345 @@
+/**
+ * senpi guide subcommands — in-shell reference for @senpi/trading-recipe.
+ *
+ * All reference text is static string constants. This is intentional: the
+ * scanner registry does not expose configSchema or description metadata at
+ * runtime (ScannerEngine.list() only returns id/enabled/intervalSeconds).
+ *
+ * TODO: replace static strings with dynamic registry metadata once
+ * ScannerEngine exposes configSchema per scanner type. Relevant type is
+ * ScannerRegistrationSummary in src/scanners/engine/engine.ts.
+ */
+const CHANGELOG_URL = "https://github.com/Senpi-ai/senpi-trading-runtime/blob/main/CHANGELOG.md";
+// ── Reference text constants ────────────────────────────────────────────────
+const OVERVIEW_TEXT = (version) => `
+@senpi/trading-recipe v${version}
+
+Event-driven automated trading plugin for OpenClaw. Orchestrates scanners,
+LLM-based trade decisions, and a DSL trailing stop-loss exit engine.
+
+Flow:  Scanner → signal queue → Action (optional LLM) → position → DSL exit
+
+Quick commands:
+  senpi guide scanners    Scanner types and config fields
+  senpi guide actions     Action types and decision modes
+  senpi guide dsl         DSL exit: phases, lock modes, tiers, time-based cuts
+  senpi guide examples    Print minimal strategy YAML
+  senpi guide schema      Full YAML schema field reference
+  senpi guide version     Plugin version and changelog URL
+
+Docs: docs/runtime-docs/
+`.trim();
+const SCANNERS_TEXT = `
+Scanner types
+─────────────────────────────────────────────────────────────────────────────
+
+emerging_movers
+  Watches the Senpi smart-money leaderboard for rank and contribution
+  movements. Stateful — compares each scan to stored history.
+  Typical interval: 20s–60s
+
+  Signal types (priority order):
+    FIRST_JUMP         (score 0.95)  10+ rank jump from deep, first appearance
+    CONTRIB_EXPLOSION  (score 0.90)  3x+ contribution spike in one scan
+    IMMEDIATE_MOVER    (score 0.85)  10+ rank jump, token was already tracked
+    NEW_ENTRY_DEEP     (score 0.80)  New entry landing directly in top 20
+    DEEP_CLIMBER       (score 0.60)  Moderate rank gain from a deep position
+
+  Config fields:
+    topN                      number   50    Track top N by SM contribution
+    minRankJump               number   5     Min rank improvement for DEEP_CLIMBER
+    minTopTradersGain         number   0.1   Min contribution threshold
+    minScansBeforeSignals     number   2     Warm-up scans before emitting signals
+    historyLimit              number   60    Max history entries per token
+    immediateJumpThreshold    number   10    Rank jump for IMMEDIATE_MOVER/FIRST_JUMP
+    deepClimbRankThreshold    number   25    Starting rank for deep-climb detection
+    contribExplosionMultiplier number  3.0   Ratio for CONTRIB_EXPLOSION
+    firstJumpMinPrevRank      number   30    Prev-rank floor for FIRST_JUMP
+
+──────────────────────────────────────────────────────────────────────────────
+
+momentum
+  Emits directional breakout signals based on candle price movement.
+  Works best paired with the prescreener scanner.
+  Typical interval: 1m
+
+  Signal types: MOMENTUM_BREAKOUT (LONG or SHORT)
+
+  Config fields:
+    timeframe           string   "1h"   Candle timeframe to analyze
+    minMovePct          number   1.5    Min price change % to emit a signal
+    maxCandidates       number   20     Max assets evaluated per scan
+    minDayVolume        number   1e6    Min 24h volume filter (fallback only)
+    minSignalScore      number   0.2    Min signal score threshold (0–1)
+    requirePrescreened  boolean  true   Only scan assets from the prescreener
+
+──────────────────────────────────────────────────────────────────────────────
+
+prescreener
+  Infrastructure scanner. Ranks liquid instruments by a composite
+  liquidity/momentum/OI score and publishes a shared artifact consumed
+  by momentum and oi_tracker. Add this scanner before those in your YAML.
+  Typical interval: 5m
+
+  Signal types: none (artifact producer only)
+
+  Config fields:
+    topN              number   30    Assets passed through to downstream scanners
+    minDayVolume      number   1e6   Min 24h notional volume
+    minLeverage       number   2     Min max-leverage (filters illiquid markets)
+    minOpenInterest   number   0     Min open interest
+
+──────────────────────────────────────────────────────────────────────────────
+
+oi_tracker
+  Infrastructure scanner. Samples open interest per instrument and writes
+  an oi-history artifact. Used by downstream scanners that need OI trend data.
+  Typical interval: 1m
+
+  Signal types: none (artifact producer only)
+
+  Config fields:
+    minDayVolume   number   1e6   Min 24h volume; instruments below are skipped
+    maxHistory     number   60    Max OI snapshots retained per instrument
+`.trim();
+const ACTIONS_TEXT = `
+Action types
+─────────────────────────────────────────────────────────────────────────────
+
+OPEN_POSITION
+  Opens a new position on Senpi. Checks slot availability before executing.
+
+  Required YAML fields:
+    action_type      OPEN_POSITION
+    decision_mode    llm | no_decision
+    scanners         list of scanner names that feed this action
+    min_confidence   0–10; signals below this score are skipped
+
+  Optional fields:
+    decision_model   Claude model id (required when decision_mode: llm)
+    context          list of context fields injected into the prompt
+                     currently supported: signal
+    decision_prompt  system prompt template; use {{signal}} for signal JSON
+
+Decision modes:
+  llm          Claude evaluates each signal. Prompt receives {{signal}} as JSON.
+               Claude must respond with:
+               {
+                 "execute": true | false,
+                 "actionType": "OPEN_POSITION",
+                 "confidence": 1–10,
+                 "reasoning": "one sentence",
+                 "payload": { "asset": "SOL", "direction": "LONG" | "SHORT" }
+               }
+               Trades are skipped when execute=false or confidence < min_confidence.
+
+  no_decision  Opens a position for every qualifying signal immediately.
+               No LLM call. Use with tight DSL stops to manage risk.
+`.trim();
+const DSL_TEXT = `
+DSL exit engine — two-phase trailing stop-loss
+─────────────────────────────────────────────────────────────────────────────
+
+The DSL monitors open positions on a configurable interval and closes them
+when price breaches the computed floor. Supports lock_mode (pctOfHighWater
+or fixedRoe), Phase 1 fixed + trailing floor, Phase 2 tiers, and optional
+Phase 1 time-based cuts (hard_timeout, weak_peak_cut, dead_weight_cut).
+
+exit:
+  engine: dsl
+  interval_seconds: 30          # how often the price monitor runs
+
+  dsl_presets:
+    <preset_name>:
+      lock_mode: pctOfHighWater  # or fixed_roe; YAML accepts snake_case
+      phase1: ...
+      phase2_trigger_tier: 0
+      phase2: ...
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 1 — Fixed floor + optional trailing
+  Active from entry until the tier at phase2_trigger_tier is crossed.
+  Floor = max(absolute_floor, trailing_floor). Absolute floor from max_loss_pct
+  (entry × (1 − max_loss_pct/100/leverage) for LONG). Trailing uses phase1
+  retraceThreshold (ROE %) so the floor can rise with high-water.
+
+  phase1:
+    max_loss_pct: 3.0                   # e.g. 3% max loss at 1×
+    consecutive_breaches_required: 3    # ticks below floor before exit
+    # Optional time-based cuts (each: enabled, interval_in_minutes):
+    #   hard_timeout, weak_peak_cut (min_value ROE %), dead_weight_cut
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 2 — Tiers + trailing floor (high-water retrace)
+  Starts when price reaches the tier at phase2_trigger_tier (0 = first tier).
+  Floor = max(tier_floor, trailing_floor). Retrace values are ROE %; the
+  engine divides by leverage for price (e.g. 1.5% ROE at 10× = 0.15% below HW).
+
+  phase2_trigger_tier: 0
+
+  phase2:
+    retrace_threshold: 1.5             # default ROE % retrace from HWM
+    consecutive_breaches_required: 1
+
+    tiers:
+      # trigger_pct = ROE % from entry that activates this tier
+      # lock_hw_pct = % of high-water ROE to lock (pctOfHighWater); floor trails every tick
+      # lock_pct    = % of (entry→HW) range to lock (fixedRoe); floor fixed at tier trigger
+      # retrace     = ROE % retrace for this tier (overrides retrace_threshold)
+      - { trigger_pct: 10,  lock_hw_pct: 50 }
+      - { trigger_pct: 20,  lock_hw_pct: 70 }
+      - { trigger_pct: 30,  lock_hw_pct: 73, retrace: 1.2 }
+      - { trigger_pct: 50,  lock_hw_pct: 80, retrace: 1.0 }
+
+──────────────────────────────────────────────────────────────────────────────
+State and events
+  Per-position state at {stateDir}/strategies/{id}/... . Close reason preserved
+  on pendingClose retry (phase1_timeout, weak_peak_cut, dead_weight_cut, dsl_breach).
+  Events: dsl.created, dsl.tier_advanced, dsl.sl_updated, dsl.phase_changed, position.closed
+`.trim();
+const SCHEMA_TEXT = `
+YAML schema — top-level keys
+─────────────────────────────────────────────────────────────────────────────
+Key              Type     Req   Description
+name             string   Yes   Strategy name
+version          string   No    Version identifier
+description      string   No    Human-readable description
+strategies       object   Yes   Keyed strategy configs (non-empty)
+scanners         array    *     Scanner definitions (* required when actions
+                                  have OPEN_POSITION or a scanners list)
+actions          array    No    Action definitions
+exit             object   No    Exit / DSL block
+health           object   No    Health check config
+hooks            array    No    Hook definitions
+notifications    object   No    e.g. telegram_chat_id
+advanced         object   No    Extra options
+
+strategies.<name>
+  wallet          string   Yes  Wallet address; supports \${VAR} substitution
+  budget          number   No   Total budget
+  slots           number   No   Max concurrent positions
+  margin_per_slot number   No   Margin per slot
+  trading_risk    string   No   conservative | moderate | aggressive
+  enabled         boolean  No   Default true
+
+scanners[]
+  name      string  Yes  Unique name referenced in actions.scanners
+  type      string  Yes  emerging_movers | momentum | prescreener | oi_tracker
+  interval  string  Yes  e.g. "30s", "2m", "1h"
+  blocked_assets  array  No
+  config    object  No   Scanner-specific config (see: senpi guide scanners)
+  advanced  object  No
+
+actions[]
+  name             string        Yes
+  action_type      string        Yes  OPEN_POSITION
+  decision_mode    string        Yes  llm | no_decision
+  decision_model   string        No   Required when decision_mode: llm
+  scanners         string[]      No   Scanner names this action listens to
+  min_confidence   number        No   0–10
+  context          string[]      No   [signal]
+  decision_prompt  string        No   Prompt template with {{signal}}
+  params           object        No
+
+exit
+  engine              string  No  dsl
+  interval_seconds    number  No  Default 30 (min 5)
+  dsl_presets         object  No  Presets keyed by name (preferred)
+  dsl                 object  No  Legacy alias for dsl_presets
+
+  Preset: lock_mode (pctOfHighWater | fixedRoe), phase1 (max_loss_pct,
+  consecutive_breaches_required, optional hard_timeout/weak_peak_cut/dead_weight_cut),
+  phase2_trigger_tier, phase2 (retrace_threshold ROE %, tiers with trigger_pct,
+  lock_hw_pct or lock_pct; tier retrace = ROE %). See: senpi guide dsl
+
+Environment substitution: \${VAR} and \${VAR:-default} resolved at load time.
+`.trim();
+const MINIMAL_YAML = `
+name: minimal
+version: 1.0.0
+description: Watch-only strategy — logs signals, opens no positions.
+
+strategies:
+  watch-only:
+    wallet: "\${WALLET_ADDRESS}"
+    budget: "0"
+    slots: 1
+    margin_per_slot: 0
+    trading_risk: conservative
+    enabled: true
+
+scanners:
+  - name: emerging_movers
+    type: emerging_movers
+    interval: 60s
+    config:
+      topN: 20
+      minRankJump: 5
+      minScansBeforeSignals: 2
+
+actions:
+  - name: log_signals
+    action_type: OPEN_POSITION
+    decision_mode: no_decision
+    scanners: [emerging_movers]
+    min_confidence: 0
+
+exit:
+  engine: dsl
+  interval_seconds: 60
+  dsl_presets:
+    default:
+      lock_mode: pctOfHighWater
+      phase1:
+        consecutive_breaches_required: 3
+        max_loss_pct: 5.0
+      phase2_trigger_tier: 0
+      phase2:
+        retrace_threshold: 1.5
+        consecutive_breaches_required: 1
+        tiers:
+          - { trigger_pct: 1, lock_hw_pct: 50 }
+`.trim();
+/**
+ * Register `senpi guide [subcommand]` on the senpi Commander subprogram.
+ * @param senpi  - the `senpi` Commander command object
+ * @param version - plugin version string (from src/version.ts)
+ */
+export function registerGuideCommands(senpi, version) {
+    const guide = senpi.command("guide")
+        .description("In-shell reference for @senpi/trading-recipe");
+    guide.action(() => {
+        process.stdout.write(OVERVIEW_TEXT(version) + "\n");
+    });
+    guide.command("scanners")
+        .description("Scanner types and config fields")
+        .action(() => {
+        process.stdout.write(SCANNERS_TEXT + "\n");
+    });
+    guide.command("actions")
+        .description("Action types and decision modes")
+        .action(() => {
+        process.stdout.write(ACTIONS_TEXT + "\n");
+    });
+    guide.command("dsl")
+        .description("DSL exit engine: phases, lock modes, tiers, time-based cuts")
+        .action(() => {
+        process.stdout.write(DSL_TEXT + "\n");
+    });
+    guide.command("examples")
+        .description("Print minimal strategy YAML to stdout")
+        .action(() => {
+        process.stdout.write(MINIMAL_YAML + "\n");
+    });
+    guide.command("schema")
+        .description("Full YAML schema field reference")
+        .action(() => {
+        process.stdout.write(SCHEMA_TEXT + "\n");
+    });
+    guide.command("version")
+        .description("Plugin version and changelog URL")
+        .action(() => {
+        process.stdout.write(`@senpi/trading-recipe v${version}\n${CHANGELOG_URL}\n`);
+    });
+}
+//# sourceMappingURL=guide-commands.js.map

package/dist/cli/guide-commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guide-commands.js","sourceRoot":"","sources":["../../src/cli/guide-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,aAAa,GACjB,0EAA0E,CAAC;AAE7E,+EAA+E;AAE/E,MAAM,aAAa,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC;yBAClB,OAAO;;;;;;;;;;;;;;;;CAgB/B,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwErB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCpB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4DhB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDnB,CAAC,IAAI,EAAE,CAAC;AAET,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6CpB,CAAC,IAAI,EAAE,CAAC;AAYT;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAuB,EACvB,OAAe;IAEf,MAAM,KAAK,GAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAsB;SACvD,WAAW,CAAC,8CAA8C,CAAC,CAAC;IAE/D,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;QAChB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,UAAU,CAAsB;SAC5C,WAAW,CAAC,iCAAiC,CAAC;SAC9C,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,SAAS,CAAsB;SAC3C,WAAW,CAAC,iCAAiC,CAAC;SAC9C,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,KAAK,CAAsB;SACvC,WAAW,CAAC,6DAA6D,CAAC;SAC1E,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,UAAU,CAAsB;SAC5C,WAAW,CAAC,uCAAuC,CAAC;SACpD,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAsB;SAC1C,WAAW,CAAC,kCAAkC,CAAC;SAC/C,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEJ,KAAK,CAAC,OAAO,CAAC,SAAS,CAAsB;SAC3C,WAAW,CAAC,kCAAkC,CAAC;SAC/C,MAAM,CAAC,GAAG,EAAE;QACX,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,OAAO,KAAK,aAAa,IAAI,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/senpi-commands.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OpenClaw CLI commands: openclaw senpi trading-strategy create | list | delete.
+ * Thin layer: all three invoke gateway RPCs only; validation and registry live in the gateway.
+ */
+/**
+ * Register senpi subcommands on the given Commander program.
+ */
+export declare function registerSenpiCli(program: {
+    command: (name: string, desc?: string) => CommanderCommand | unknown;
+}): void;
+/** Minimal Commander command type for subcommands and options. */
+interface CommanderCommand {
+    command(name: string, desc?: string): CommanderCommand;
+    description(desc: string): CommanderCommand;
+    option(flags: string, description?: string): CommanderCommand;
+    requiredOption(flags: string, description?: string): CommanderCommand;
+    action(fn: (opts: Record<string, unknown>) => void | Promise<void>): CommanderCommand;
+}
+export {};
+//# sourceMappingURL=senpi-commands.d.ts.map

package/dist/cli/senpi-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"senpi-commands.d.ts","sourceRoot":"","sources":["../../src/cli/senpi-commands.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE;IAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,gBAAgB,GAAG,OAAO,CAAA;CAAE,GAChF,IAAI,CAgHN;AAED,kEAAkE;AAClE,UAAU,gBAAgB;IACxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAC9D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACtE,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;CACvF"}

package/dist/cli/senpi-commands.js

@@ -0,0 +1,115 @@
+/**
+ * OpenClaw CLI commands: openclaw senpi trading-strategy create | list | delete.
+ * Thin layer: all three invoke gateway RPCs only; validation and registry live in the gateway.
+ */
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { registerGuideCommands } from "./guide-commands.js";
+import { VERSION } from "../version.js";
+/**
+ * Register senpi subcommands on the given Commander program.
+ */
+export function registerSenpiCli(program) {
+    const senpi = program.command("senpi");
+    senpi.description("Senpi trading recipe: trading-strategy create, list, delete");
+    const tradingStrategy = senpi.command("trading-strategy");
+    tradingStrategy.description("Manage trading strategies");
+    tradingStrategy
+        .command("create")
+        .description("Add a strategy from a YAML file or paste YAML; the gateway validates and runs it")
+        .option("-p, --path <path>", "Path to your strategy YAML file")
+        .option("-c, --content <content>", "Paste YAML content directly")
+        .option("--strategy-id <id>", "Name for this strategy (default: from file name or content)")
+        .action(async (opts) => {
+        const hasPath = typeof opts.path === "string" && opts.path.length > 0;
+        const hasContent = typeof opts.content === "string";
+        if (hasPath && hasContent) {
+            console.error("Please provide either a file path (--path) or YAML content (--content), not both.\nExample: openclaw senpi trading-strategy create -p my-strategy.yaml");
+            process.exitCode = 1;
+            return;
+        }
+        if (!hasPath && !hasContent) {
+            console.error("Please provide your strategy: either a path to a YAML file (--path) or the YAML content (--content).\nExample: openclaw senpi trading-strategy create -p my-strategy.yaml\nTo see a sample YAML: openclaw senpi guide examples");
+            process.exitCode = 1;
+            return;
+        }
+        let content;
+        if (hasPath) {
+            try {
+                content = readFileSync(path.resolve(process.cwd(), opts.path), "utf8");
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                const isNotFound = msg.includes("ENOENT") || msg.includes("no such file");
+                if (isNotFound) {
+                    console.error(`Could not find the file "${opts.path}". Please check the path is correct and the file exists.`);
+                }
+                else {
+                    console.error(`Could not read the file. ${msg}`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+        }
+        else {
+            content = opts.content;
+        }
+        const params = {
+            tradingStrategyYamlContent: content,
+            ...(typeof opts.strategyId === "string" && opts.strategyId.length > 0 ? { id: opts.strategyId } : {}),
+        };
+        const result = spawnSync(process.argv[0], [process.argv[1], "gateway", "call", "senpi.installStrategy", "--params", JSON.stringify(params)], {
+            stdio: "inherit",
+            cwd: process.cwd(),
+        });
+        process.exitCode = result.status ?? 1;
+    });
+    tradingStrategy
+        .command("delete <trading_strategy_id>")
+        .description("Remove a strategy (use the id from 'trading-strategy list')")
+        .action(async (tradingStrategyIdOrOpts) => {
+        const tradingStrategyId = typeof tradingStrategyIdOrOpts === "string" ? tradingStrategyIdOrOpts : "";
+        if (tradingStrategyId.length === 0) {
+            console.error("Please provide the strategy id (the name you used when creating it).\nExample: openclaw senpi trading-strategy delete my-strategy\nTo list installed strategies: openclaw senpi trading-strategy list");
+            process.exitCode = 1;
+            return;
+        }
+        const result = spawnSync(process.argv[0], [process.argv[1], "gateway", "call", "senpi.deleteStrategy", "--params", JSON.stringify({ id: tradingStrategyId })], { stdio: "inherit", cwd: process.cwd() });
+        process.exitCode = result.status ?? 1;
+    });
+    tradingStrategy
+        .command("list")
+        .description("List all installed strategies with their id, source, and status (running/stopped)")
+        .action(async () => {
+        const result = spawnSync(process.argv[0], [process.argv[1], "gateway", "call", "senpi.listStrategies", "--json", "--params", "{}"], {
+            stdio: ["inherit", "pipe", "inherit"],
+            cwd: process.cwd(),
+            encoding: "utf8",
+        });
+        if (result.status !== 0) {
+            process.exitCode = result.status ?? 1;
+            console.error("\nTip: If the gateway is not running, start it with: openclaw gateway run");
+            return;
+        }
+        let data;
+        try {
+            data = JSON.parse(result.stdout ?? "{}");
+        }
+        catch {
+            process.stdout.write(result.stdout ?? "");
+            return;
+        }
+        const strategies = data.payload?.strategies ?? data.strategies ?? [];
+        if (strategies.length === 0) {
+            console.log("No strategies installed.");
+            return;
+        }
+        console.log("id\t\tsource\t\tstatus");
+        for (const s of strategies) {
+            console.log(`${s.id}\t\t${s.source ?? "(inline)"}\t\t${s.status ?? "—"}`);
+        }
+    });
+    registerGuideCommands(senpi, VERSION);
+}
+//# sourceMappingURL=senpi-commands.js.map