@senpi/runtime 1.0.95-dev.20260408174401

package/dist/cli/guide-commands.js

@@ -0,0 +1,481 @@
+/**
+ * senpi guide subcommands — in-shell reference for @senpi-ai/runtime.
+ *
+ * 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-ai/runtime 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 dsl positions     Active DSL positions (CLI inspection)
+  senpi dsl inspect       Full DSL state for one asset
+  senpi dsl closes        Archived closes with reason
+  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
+
+──────────────────────────────────────────────────────────────────────────────
+
+position_tracker
+  Wallet position monitor: compares clearing-house snapshots and emits lifecycle deltas.
+  Use with action POSITION_TRACKER to feed the DSL exit engine.
+  Typical interval: 10s–60s
+
+  Type aliases (same scanner): position-tracker
+
+  Scanner signal types (signalType per result — not YAML action_type values):
+    POSITION_OPENED, POSITION_CLOSED, POSITION_INCREASED,
+    POSITION_DECREASED, POSITION_FLIPPED
+  Use action_type: POSITION_TRACKER with scanners: […] to handle these for DSL/hooks.
+
+  Config fields:
+    sizeChangeEpsilon   number   1e-9   Treat abs(size diff) below this as unchanged (float noise)
+`.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
+
+  XYZ DEX (Hyperliquid xyz book): payload may use base + payload.dex "xyz" (e.g. GOLD), or
+  xyz:BASE with or without dex set; the DSL layer normalizes to stored state { asset: base, dex }.
+  Main book: plain symbols (e.g. BTC). CLOSE_POSITION: same hook shapes; include dex when closing
+  xyz-book positions so DSL can resolve state (optional if only one open position matches the base).
+
+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 (DSL v2)
+─────────────────────────────────────────────────────────────────────────────
+
+The DSL monitors open positions on a configurable interval and closes them
+when price breaches the computed floor or when preset time cuts fire.
+Phase 1: max_loss absolute floor + phase1 retrace from high-water; consecutive
+breach counting applies only in phase 1. Phase 2: tier floors from lock_hw_pct
+(% of current high-water ROE); phase 2 begins when price crosses the first
+tier (no phase2_trigger_tier). Optional hard_timeout, weak_peak_cut, and
+dead_weight_cut live on the preset (not nested under phase1). When any of these
+has enabled: true, interval_in_minutes is required (finite number > 0);
+weak_peak_cut also requires min_value (finite ROE % > 0). hard_timeout
+applies only in phase 1: entering phase 2 before the interval elapses cancels it;
+same tick as first tier (phase 2) skips hard_timeout in favor of tier advance.
+dead_weight_cut: stagnation clock resets every tick while current ROE > 0 (mark vs entry);
+after interval_in_minutes with current ROE ≤ 0 on the tick, close with dead_weight_cut.
+
+exit:
+  engine: dsl
+  interval_seconds: 30
+
+  dsl_preset:
+    hard_timeout: ...             # optional; same level as phase1 / phase2
+    weak_peak_cut: ...
+    dead_weight_cut: ...
+    phase1: ...
+    phase2: ...
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 1 — Fixed floor + high-water trailing
+  Floor = max(absolute_floor, trailing_floor). Absolute floor from max_loss_pct
+  (entry × (1 − max_loss_pct/100/leverage) for LONG). Trailing uses phase1
+  retrace_threshold (ROE %) from high-water.
+
+  phase1:
+    # enabled: false                    # optional; default true — false = skip Phase 1 logic; tiers can still advance
+    max_loss_pct: 3.0                   # e.g. 3% max loss at 1×
+    retrace_threshold: 10               # ROE % retrace from HWM in phase 1 (required when enabled)
+    consecutive_breaches_required: 3    # ticks below floor before exit in phase 1 only (required when enabled)
+    # Exchange SL in Phase 1: max_loss absolute floor only; tighter engine floors use closePosition.
+
+──────────────────────────────────────────────────────────────────────────────
+Phase 2 — Tier floors (no per-tier breaches or retrace YAML)
+  Floor = tier floor from lock_hw_pct once the tier is active. Price below
+  effective floor closes immediately (no consecutive breach counter in phase 2).
+  Exchange SL tracks the full effective floor (editPosition on tier/phase and moves).
+
+  phase2:
+    # enabled: false                    # optional; default true — false = never enter phase 2
+    tiers:
+      # trigger_pct = ROE % from entry that activates this tier (strictly increasing list)
+      # lock_hw_pct = required; % of current high-water ROE to lock (0–100)
+      - { trigger_pct: 10,  lock_hw_pct: 50 }
+      - { trigger_pct: 20,  lock_hw_pct: 70 }
+
+Legacy keys removed: phase2_trigger_tier; phase2.retrace_threshold / consecutive_breaches_required;
+tier breaches / retrace; phase1-nested time cuts (use preset hard_timeout / weak_peak_cut / dead_weight_cut).
+
+──────────────────────────────────────────────────────────────────────────────
+State and events
+  Per-position state under stateDir; on-disk version must match the runtime.
+  Close reasons include exchange_sl_hit, hard_timeout, weak_peak_cut, dead_weight_cut, dsl_breach, etc.
+  Close reason is preserved on pendingClose retry. DSL bus events: dsl.created, dsl.tier_advanced,
+  dsl.sl_updated, dsl.phase_changed, dsl.closed, dsl.deleted, and hook position.closed /
+  on_position_increased / on_position_decreased (same hook names as HookSystem.fire).
+
+──────────────────────────────────────────────────────────────────────────────
+Commands
+  senpi dsl positions              List active DSL-tracked positions
+  senpi dsl positions --json       Output as JSON
+  senpi dsl inspect <asset>        Full state for one position (e.g. SOL, xyz:GOLD)
+  senpi dsl inspect <asset> --json Output full DslState as JSON
+  senpi dsl closes                 List archived closes with reason and PnL
+  senpi dsl closes --limit 20      Limit output
+`.trim();
+const SCHEMA_TEXT = `
+YAML schema — top-level keys
+─────────────────────────────────────────────────────────────────────────────
+Key              Type     Req   Description
+name             string   Yes   Recipe name
+version          number/string  No    Recipe version (default: 1). Integer or semver string; major version is the schema version.
+description      string   No    Human-readable description
+strategy         object   Yes   Single strategy config (wallet, budget, slots, etc.)
+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    telegram_chat_id; gateway_token optional
+                                  (defaults to OPENCLAW_GATEWAY_TOKEN env).
+                                  Optional dsl_lifecycle (false disables DSL Telegram),
+                                  dsl_notify_sl_updates (true = noisy SL sync)
+advanced         object   No    Extra options
+
+strategy
+  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; integer 5–3600 (Zod + DSL parse)
+  dsl_preset          object  No  Single exit profile (required to start DslPlugin)
+  sm_flip             any     No  Non-DSL exit hook data (allowed; ignored by DSL parse)
+
+  Preset: max_loss_pct (or phase1.max_loss_pct), phase1 (optional enabled;
+  max_loss_pct, retrace_threshold ROE %, consecutive_breaches_required),
+  phase2 (optional enabled; tiers only — trigger_pct, lock_hw_pct per row),
+  optional hard_timeout / weak_peak_cut / dead_weight_cut at preset root
+  (when enabled: true, require interval_in_minutes; weak_peak_cut also min_value).
+  phase1.enabled and phase2.enabled cannot both be false. Each tier row:
+  lock_hw_pct [0,100]. Unknown keys under exit / presets / phase1 / phase2 / tiers throw
+  DslConfigValidationError (UNKNOWN_DSL_CONFIG_KEY) at load. DSL parse also
+  enforces strictly increasing trigger_pct per tier list, bounds on
+  interval/max_loss/trigger/lock_hw, and integer breach counts; see dsl-reference
+  Config validation. 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.
+
+strategy:
+  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_preset:
+    phase1:
+      consecutive_breaches_required: 3
+      max_loss_pct: 5.0
+      retrace_threshold: 10
+    phase2:
+      tiers:
+        - { trigger_pct: 1, lock_hw_pct: 50 }
+`.trim();
+export const CHEATSHEET_TEXT = `
+Senpi Plugin Commands Cheatsheet
+================================
+
+All CLI commands and gateway methods exposed by @senpi-ai/runtime.
+
+CLI Commands
+------------
+All commands are prefixed with: openclaw senpi
+
+senpi config — Manage CLI preferences (~/.openclaw/senpi-cli.json)
+  config set-chat-id <chatId>          Store Telegram chat ID for lifecycle notifications
+  config set-senpi-jwt-token <token>   Store Senpi MCP JWT (Bearer)
+  config set-state-dir <dir>           Set base state directory
+  config get <key>                     Print one value (telegram-chat-id | senpi-jwt-token | state-dir)
+  config list                          List all preferences (secrets masked)
+  config unset <key>                   Remove a key
+  config reset                         Clear all preferences
+
+senpi runtime — Manage runtimes
+  runtime create                       Add a runtime from a YAML file
+    -p, --path <path>                    Path to strategy YAML file
+    -c, --content <yaml>                 Inline YAML content
+    --runtime-id <id>                    Override auto-derived ID
+  runtime delete [id]                  Remove a runtime
+    --id <runtime_id>                    Delete by runtime ID
+    --address <wallet>                   Delete by wallet address
+  runtime list                         List installed runtimes (id, wallet, source, status)
+
+senpi dsl — Inspect DSL exit engine
+  dsl positions                        Active DSL-tracked positions
+    -r, --runtime <id>                   Filter by runtime ID
+    -a, --address <addr>                 Filter by strategy address
+    --json                               Raw JSON output
+  dsl inspect <asset>                  Full DSL state for one position
+    -r, --runtime <id>                   Filter by runtime ID
+    -a, --address <addr>                 Filter by strategy address
+    --json                               Raw JSON output
+  dsl closes                           Archived closes with reason and ROE
+    -r, --runtime <id>                   Filter by runtime ID
+    -a, --address <addr>                 Filter by strategy address
+    -l, --limit <n>                      Max rows
+    --json                               Raw JSON output
+
+senpi guide — In-shell reference
+  guide                                Overview and quick commands
+  guide scanners                       Scanner types and config fields
+  guide actions                        Action types and decision modes
+  guide dsl                            DSL exit engine reference
+  guide examples                       Print minimal strategy YAML
+  guide schema                         Full YAML schema field reference
+  guide version                        Plugin version and changelog URL
+
+Gateway Methods
+---------------
+Called via: openclaw gateway call <method> --params '<json>'
+Responses: { ok: boolean, payload?: ..., error?: { code, message } }
+
+senpi.installRuntime
+  Params:  runtimeYamlPath (string) OR runtimeYamlContent (string); id (string, optional)
+  Success: { id, name, wallet }
+  Errors:  INVALID_REQUEST (missing YAML, duplicate ID/wallet), UNAVAILABLE (bad YAML, start failure)
+
+senpi.listRuntimes
+  Params:  (none)
+  Success: { recipes: [{ id, wallet, source, status }] }
+
+senpi.deleteRuntime
+  Params:  id (string) OR address (string)
+  Success: { id }
+  Errors:  NOT_FOUND, INVALID_REQUEST
+
+senpi.listDslPositions
+  Params:  runtimeId? (string), address? (string)
+  Success: { positions: [{ runtimeId, address, asset, direction, entryPrice, lastPrice,
+             currentROE, phase, currentTierIndex, floorPrice, currentBreachCount,
+             breachesRequired, elapsedMinutes, pendingClose }] }
+
+senpi.getDslPositionState
+  Params:  asset (string, required), runtimeId? (string), address? (string)
+  Success: { positions: [{ runtimeId, address, state: <full DslState> }] }
+  Errors:  INVALID_REQUEST (no asset), NOT_FOUND
+
+senpi.listDslArchives
+  Params:  runtimeId? (string), address? (string), limit? (number)
+  Success: { closes: [{ runtimeId, address, asset, direction, entryPrice, lastPrice,
+             closeReason, closedAt, peakROE, currentROE, elapsedMinutes, phase }] }
+  Close reasons: dsl_breach, hard_timeout, weak_peak_cut, dead_weight_cut, exchange_sl_hit, manual
+
+Full cheatsheet with sample responses: docs/plugin-commands-cheatsheet.md
+`.trim();
+/**
+ * Register `senpi guide [subcommand]` on the senpi Commander subprogram.
+ * @param senpi  - the `senpi` Commander command object
+ * @param version - plugin version string (from package.json; see `src/version.ts`)
+ */
+export function registerGuideCommands(senpi, version) {
+    const guide = senpi.command("guide")
+        .description("In-shell reference for @senpi-ai/runtime");
+    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-ai/runtime 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":"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"}

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

@@ -0,0 +1,33 @@
+/**
+ * Persistent Senpi CLI preferences: ~/.openclaw/senpi-cli.json (override via OPENCLAW_SENPI_CLI_CONFIG).
+ * Priority when resolving at runtime: plugin config > stored file > env > default (per key).
+ */
+export declare const SENPI_CLI_KEYS: {
+    readonly TELEGRAM_CHAT_ID: "telegram-chat-id";
+    readonly SENPI_JWT_TOKEN: "senpi-jwt-token";
+    readonly STATE_DIR: "state-dir";
+};
+export type SenpiCliKey = (typeof SENPI_CLI_KEYS)[keyof typeof SENPI_CLI_KEYS];
+/** Last 4 chars masked as ••••••••abcd */
+export declare function maskSensitiveValue(value: string): string;
+export declare function formatConfigListValue(key: string, value: string | undefined): string;
+export declare function getSenpiCliConfigPath(): string;
+export declare function readSenpiCliStore(): Record<string, string>;
+export declare function writeSenpiCliStore(store: Record<string, string>): void;
+export declare function setSenpiCliKey(key: string, value: string): void;
+export declare function unsetSenpiCliKey(key: string): void;
+export declare function resetSenpiCliStore(): void;
+/** Telegram lifecycle notifications: stored > TELEGRAM_CHAT_ID > SENPI_LIFECYCLE_TELEGRAM_CHAT_ID */
+export declare function resolveTelegramChatIdFromStore(store: Record<string, string>): string | undefined;
+/** MCP JWT / API key: plugin config > stored > SENPI_API_KEY */
+export declare function resolveSenpiApiKeyFromStore(store: Record<string, string>, configApiKey: string | undefined): string | undefined;
+/**
+ * Base Senpi state directory (registry root): plugin stateDir > stored > SENPI_STATE_DIR > OpenClaw state/senpi-state > ~/.openclaw/senpi-state
+ */
+export declare function resolveSenpiBaseStateDir(options: {
+    store: Record<string, string>;
+    configStateDir: string | undefined;
+    resolveOpenclawStateDir: (() => string) | undefined;
+    getDefaultStateDir: () => string;
+}): string;
+//# sourceMappingURL=senpi-cli-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"senpi-cli-config.d.ts","sourceRoot":"","sources":["../../src/cli/senpi-cli-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAI/E,0CAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAIpF;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAYD,wBAAgB,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAe1D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAItE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI/D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIlD;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,qGAAqG;AACrG,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAQhG;AAED,gEAAgE;AAChE,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAQpB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,uBAAuB,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IACpD,kBAAkB,EAAE,MAAM,MAAM,CAAC;CAClC,GAAG,MAAM,CAaT"}

package/dist/cli/senpi-cli-config.js

@@ -0,0 +1,130 @@
+/**
+ * Persistent Senpi CLI preferences: ~/.openclaw/senpi-cli.json (override via OPENCLAW_SENPI_CLI_CONFIG).
+ * Priority when resolving at runtime: plugin config > stored file > env > default (per key).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const SENPI_CLI_KEYS = {
+    TELEGRAM_CHAT_ID: "telegram-chat-id",
+    SENPI_JWT_TOKEN: "senpi-jwt-token",
+    STATE_DIR: "state-dir",
+};
+const SENSITIVE_KEYS = new Set([SENPI_CLI_KEYS.SENPI_JWT_TOKEN]);
+/** Last 4 chars masked as ••••••••abcd */
+export function maskSensitiveValue(value) {
+    const t = value.trim();
+    if (t.length <= 4)
+        return t.length > 0 ? "••••" : "(empty)";
+    return `••••••••${t.slice(-4)}`;
+}
+export function formatConfigListValue(key, value) {
+    if (value === undefined || value.length === 0)
+        return "(not set)";
+    if (SENSITIVE_KEYS.has(key))
+        return maskSensitiveValue(value);
+    return value;
+}
+export function getSenpiCliConfigPath() {
+    const override = process.env.OPENCLAW_SENPI_CLI_CONFIG?.trim();
+    if (override)
+        return override;
+    const home = homedir();
+    if (!home)
+        return join(process.cwd(), ".openclaw", "senpi-cli.json");
+    return join(home, ".openclaw", "senpi-cli.json");
+}
+function expandUserPath(p) {
+    const t = p.trim();
+    if (t.startsWith("~/") || t === "~") {
+        const h = homedir();
+        if (!h)
+            return t.replace(/^~/, "");
+        return t === "~" ? h : join(h, t.slice(2));
+    }
+    return t;
+}
+export function readSenpiCliStore() {
+    const path = getSenpiCliConfigPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = readFileSync(path, "utf8");
+        const o = JSON.parse(raw);
+        if (!o || typeof o !== "object" || Array.isArray(o))
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(o)) {
+            if (typeof v === "string" && v.length > 0)
+                out[k] = v;
+        }
+        return out;
+    }
+    catch {
+        return {};
+    }
+}
+export function writeSenpiCliStore(store) {
+    const path = getSenpiCliConfigPath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+}
+export function setSenpiCliKey(key, value) {
+    const store = readSenpiCliStore();
+    store[key] = value.trim();
+    writeSenpiCliStore(store);
+}
+export function unsetSenpiCliKey(key) {
+    const store = readSenpiCliStore();
+    delete store[key];
+    writeSenpiCliStore(store);
+}
+export function resetSenpiCliStore() {
+    writeSenpiCliStore({});
+}
+/** Telegram lifecycle notifications: stored > TELEGRAM_CHAT_ID > SENPI_LIFECYCLE_TELEGRAM_CHAT_ID */
+export function resolveTelegramChatIdFromStore(store) {
+    const a = store[SENPI_CLI_KEYS.TELEGRAM_CHAT_ID]?.trim();
+    if (a)
+        return a;
+    const e1 = process.env.TELEGRAM_CHAT_ID?.trim();
+    if (e1)
+        return e1;
+    const e2 = process.env.SENPI_LIFECYCLE_TELEGRAM_CHAT_ID?.trim();
+    if (e2)
+        return e2;
+    return undefined;
+}
+/** MCP JWT / API key: plugin config > stored > SENPI_API_KEY */
+export function resolveSenpiApiKeyFromStore(store, configApiKey) {
+    const c = configApiKey?.trim();
+    if (c)
+        return c;
+    const s = store[SENPI_CLI_KEYS.SENPI_JWT_TOKEN]?.trim();
+    if (s)
+        return s;
+    const e = process.env.SENPI_API_KEY?.trim();
+    if (e)
+        return e;
+    return undefined;
+}
+/**
+ * Base Senpi state directory (registry root): plugin stateDir > stored > SENPI_STATE_DIR > OpenClaw state/senpi-state > ~/.openclaw/senpi-state
+ */
+export function resolveSenpiBaseStateDir(options) {
+    const { store, configStateDir, resolveOpenclawStateDir, getDefaultStateDir: defaultDir } = options;
+    if (typeof configStateDir === "string" && configStateDir.trim().length > 0) {
+        return expandUserPath(configStateDir);
+    }
+    const stored = store[SENPI_CLI_KEYS.STATE_DIR]?.trim();
+    if (stored)
+        return expandUserPath(stored);
+    const env = process.env.SENPI_STATE_DIR?.trim();
+    if (env)
+        return expandUserPath(env);
+    if (typeof resolveOpenclawStateDir === "function") {
+        return join(resolveOpenclawStateDir(), "senpi-state");
+    }
+    return defaultDir();
+}
+//# sourceMappingURL=senpi-cli-config.js.map

package/dist/cli/senpi-cli-config.js.map

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