senpi-trading-runtime

Senpi Trading Runtime — ランタイムの契約

このスキルはインフラストラクチャです。Senpi ランタイム（@senpi-ai/runtime）の動作と、ストラテジーがランタイムとどのように連携するかについての正規の知識です。ライフサイクルスキルである author（ビルド）、ops（インストール／監視）、discover（推奨）は、このスキルを契約の参照元とします。

ランタイムのモデル

ストラテジーは、リポジトリ内の Python モジュールを指定する**runtime.yamlから実行されます。ランタイムはそのモジュールを起動して監視**し、interval_seconds ごとに固定された scan(inputs, ctx) を呼び出します。役割分担は固定されています。

• コードが生成するのはシグナルだけです。それ以外は何もしません。 scan(inputs, ctx) は市場データとアカウントデータを読み取り、候補シグナルの list[dict] を返します。何かを開始、終了、サイズ設定、スケジュール、実行することはありません。
• モデルコストはゼロで、ループはこれだけです。 ランタイムはモデル呼び出しなしで interval_seconds ごとに動作します。その横にエージェントターンの cron（シグナル生成、再チェック、監視）を決して配置しないでください。実行のたびにモデル呼び出しが発生します。ペーパートレードモードはありません。ストラテジーは senpi validate（実際のティックを1回実行、ウォレット不要）でテストした後、最低額 $10 でライブ実行します。
• それ以降のすべてはランタイムが担います。 スケジューリング（interval_seconds）、スキャナーの起動・監視・再起動、返されたシグナルの検証（signal_data_schema）と重複排除、サイズ設定と注文実行（FEE_OPTIMIZED_LIMIT）、スロット管理、risk.guard_rails、二段階のDSLトレーリングストップ決済、そして再起動時のクラッシュセーフなポジション照合です。
• ランタイムが担わないこと：部分決済です。 ランタイムが実行できるすべての決済（DSL、CLOSE_POSITION）はポジション全体を決済します。また、唯一の縮小手段である edit_position はスキャナーからブロックされています。「ROE が +10% になったら25%を利確し、残りは保有する」といったルールは、ランタイムパッケージでは作成できません。このルールを試みるスキャナーは、ログ上ではルールが機能しているように見える一方、毎ティック PermissionError を発生させます。詳細：references/runtime-concepts.md → DSL Exit Engine。

コードからランタイムへの連携方法

連携の仕組みは小さく、一方向です。データを読み取り、シグナルを返し、ランタイムが実行します。

• runtime.yaml はスキャナー、アクションゲート、決済エンジン、リスクガードレールを宣言し、inputs: 経由で作成者が設定可能な値を渡します。→ references/runtime-yaml.md
• scan(inputs, ctx) が唯一のエントリーポイントです。inputs はランタイムの inputs: マップです。ctx には次の情報が含まれます。
  • ctx.senpi_mcp.call_tool(name, args) — Senpi MCP クライアントです。読み取り専用で、市場、アカウント、リーダーボード、ディスカバリー、strategy_get* などを参照できます。データ取得に使える唯一の方法です。
  • ctx.state — 重複排除、ローテーション、初回検出の台帳に使う、トランザクション対応のランタイム永続履歴（last()／append()／len）です。ティックが正常に完了した場合にのみ進みます。
  • ctx.wallet — ストラテジーのウォレットアドレスです。
  • → references/scan-contract.md
• 戻り値は候補シグナルごとに1つの list[dict] で、各シグナルは asset、direction、marginPct、leverage、data{} を含みます。ランタイムは各 data{} を runtime.yaml の signal_data_schema に照らして検証し、その後、サイズ設定、実行、決済管理を行います。

投資方針のロジックは、兄弟ファイルの純粋な scoring.py（I/O も MCP も使用しない）に置いて、ユニットテスト可能にしてください。scan.py はデータの読み取りと状態管理を行い、scoring.py は計算を行います。

ランタイムコマンド（基本）

プラグインはゲートウェイに senpi コマンドグループを登録します。ストラテジーのデプロイと確認：

openclaw plugins install @senpi-ai/runtime
openclaw senpi validate <dir-with-runtime.yaml>        # THE GATE, pre-money: one real tick, no wallet; a PASS records the proof deploy requires
openclaw senpi deploy -p <package-dir> --budget <usd>  # ONE verb, detached: funds preflight → wallet create+fund → install → one observed tick
openclaw senpi deploy status                           # poll until terminal; the verified report (read-only)
openclaw senpi runtime list                            # id, source, status ("running — NO ENTRY SCANNERS" = scanners never wired)

**senpi-strategy-ops の deploy.py create <id> --budget <usd> を通じてパッケージをデプロイしてください。パッケージを解決し、構造上の事前チェックを実行して、同じコマンドを実行します。このコマンドが各ゲートを担います。ライブユニバースの確認（[E_UNIVERSE_NOT_LIVE]、資金投入前）、資金の事前チェック、skillName／skillVersion の帰属情報、検証済みティックが含まれます。runtime create は内部用です。**ランタイムをインストールしますが、これらのチェックをすべて省略するため、デプロイには使用しません。 senpi validate は、すべてのデプロイが通過するゲートです — スキャナーを読み込み、ウォレットも資金もない状態で実際のティックを1回実行します。ライブの深度でスコープ指定なしの完全な PASS を得ると、.senpi-proof.json が書き込まれます。これがないと senpi deploy はパッケージへの資金投入を拒否します。deploy の前に、インスタンスごとに1回、そのインスタンスの runtime.yaml が格納されたディレクトリを指定して実行してください。

稼働中のストラテジーを変更する場合 → 削除して再デプロイするのではなく、openclaw senpi update を使います。ランタイムを削除すると、その DSL のポジションファイルが放棄され、すべてのオープンポジションで、ストラテジーがすでに約束していたトレーリングストップが失われます。新しいランタイムは、見つかった価格で一から再取得します。update はコンポーネントをその場で入れ替え、DSL の状態、スキャナーストア、アクション履歴を保持します — ウォレットは作成されず、資金も投入されず、ポジションもクローズされません。

openclaw senpi update ./pkg                       # PLAN — what changes, what it leaves alone
openclaw senpi update ./pkg --apply               # commit (needs the same proof deploy needs)
openclaw senpi update ./pkg --apply --code-only   # assert only scan.py changed; refuses if not

デフォルトでは計画のみを行い、変更を確定できるのは --apply だけです。phase2.tiers はユーザーが ラチェット と呼ぶものです。オープンポジションがなければ、編集して --apply を実行するだけで変更は完了です。dsl_preset の変更は今後のポジションにのみ反映されます — 新規エントリーに限られ、オープンポジションはそれぞれ、建てたときのプリセットのスナップショットを保持します（order_type など、その他の exit: フィールドはライブで読み込まれ、オープンポジションにも反映されます）。以下の変更は一切受け付けず、何も変更しません。strategy.wallet の変更（新規デプロイが必要で、旧ウォレットのポジションが管理されなくなるため）、外部スキャナーの名前変更または移動（状態は名前とポジションの組み合わせでキー付けされ、外部スキャナーを挿入または削除すると、その下にあるすべての外部スキャナーが移動するためです。末尾への追加なら何も移動しないため許可されます）、安定した名前のままの action_type の変更。--apply には、適用するレシピを対象にした合格済みの proof も必要です。そのため、パッケージのディレクトリを指定してください。テキストだけで渡されたレシピは検証対象がなく、拒否されます。終了コード 2 はランタイムに一切触れていないことを示します。終了コード 1 は apply を試みており、元の状態のままではない可能性があることを示します。再試行する前にメッセージを確認してください。

保存しただけでは適用されていません。 --apply を付けない限り、update は何も変更しません。そのことを示すのは出力の最初の行だけです — Dry run for <runtime_id> — nothing has been applied. — そのため、openclaw senpi の出力を tail や head にパイプで渡さないでください。スキャナーが scan.py を読み込むのは起動時の1回だけなので、稼働中のストラテジーは、--apply によってスキャナーが再起動されるまで古いコードを使い続けます（クラッシュやゲートウェイの再起動が起きると、編集内容が予告なく読み込まれることもあります）。senpi validate が実行するのはディスク上のコピーであり、稼働中のコピーではありません。また、すでに稼働中のストラテジーに対して deploy を再実行しても、何も適用されません。apply の終了コードが 0 で、最初の行が Updated <runtime_id>. となり、外部スキャナーが稼働していないことを示す WARNING がなく、さらに稼働中のストラテジーにも変更が反映されていれば、編集内容は反映済みです。

openclaw senpi events -r <runtime_id> --name runtime.updated   # an entry for this apply (code-only edits too)
openclaw senpi update ./pkg --id <runtime_id>                  # read-only: a recipe edit that landed plans "The recipe is unchanged."

両方の確認結果に反映されるまでは、編集内容は保存済みで、未適用だとユーザーに伝えてください。ティックが保持するものと破棄するものについては、references/scan-contract.md を参照してください。

validate、deploy／deploy status、update、runtime list/delete に加え、CLI ではランタイムのライブ状態を確認できます — senpi dsl positions|inspect|closes（退出エンジン）、senpi action list|inspect|history|decisions（意思決定レイヤー）、senpi risk（取引が許可されているか、許可されていない場合はその理由）、senpi audit（AI の推論を含むバックエンドの取引履歴）、senpi scanner（スキャナーごとの健全性と稼働状況、および実行されているのに何も生成しないスキャナーを示す (no signals yet) フラグ）、senpi events／senpi explain <asset>（ローカルのドメインイベントログ — 取引の経緯と、1つのアセットのつなぎ合わせたライフサイクル）、senpi status／senpi state（健全性 — フェイルクローズ方式です。ティックで一度も確認されていない外部スキャナーの状態は healthy ではなく unknown と表示されます。健全でないスキャナーについては、再起動回数と原因を含む専用の行が表示されます）、senpi guide …（シェル内のリファレンス）。すべてのオプションを含む全コマンド一覧 → references/runtime-cli.md。 未決済のポジションが実際にストップロスで保護されていることを確認するには（DSL が設定されていないポジションは dsl positions に 表示されないため、見落としやすいです）→ references/dsl-protection-check.md の判定手順を参照してください。

リファレンス一覧

こちらを読む	内容
references/runtime-concepts.md	ランタイムのエンドツーエンドの動作：ランタイムパイプライン、position_tracker、2 フェーズの DSL 決済エンジン
references/runtime-yaml.md	runtime.yaml のスキーマ — すべてのセクション、external_scanner のフィールド、リスクガードレール
references/scan-contract.md	作成者向け契約の詳細：scan(inputs, ctx)、ctx の公開インターフェイス、シグナルの形式、scoring.py
references/runtime-cli.md	openclaw senpi … の全コマンド — validate（デプロイ前のゲート：フラグ、深度、終了コード、記録される証跡）、deploy、runtime、dsl、action、status/state、skills、guide
references/dsl-protection-check.md	未決済のポジションが DSL で保護されていることを確認する — PROTECTED／UNPROTECTED／STOP-NOT-ON-VENUE の判定と、未決済ポジションと追跡対象ポジションの照合

パッケージ名（重要）

ランタイムパッケージは @senpi-ai/runtime（-ai 付き）です。ホストにインストールするのはこちらです。 必ず -ai を付けて記載してください。