senpi-trading-runtime

Senpi Trading Runtime — the runtime contract

This skill is infrastructure: the canonical knowledge of how the Senpi runtime (@senpi-ai/runtime) behaves and how a strategy interacts with it. The lifecycle skills — author (build), ops (install/monitor), discover (recommend) — reference this one for the contract.

The runtime model

A strategy runs from a runtime.yaml that points at an in-repo Python module. The runtime spawns and supervises that module and calls a frozen scan(inputs, ctx) every interval_seconds. The division of labor is fixed:

• Your code produces signals — nothing else. scan(inputs, ctx) reads market and account data and returns a list[dict] of candidate signals. It does not open, close, size, schedule, or execute anything.
• Zero model cost, and the only loop there is. The runtime ticks every interval_seconds without a model call. Never put an agent-turn cron beside it — a producer, a re-check, a watcher — each firing is a full model call. There is no paper-trading mode: a strategy is tested with senpi validate (one real tick, no wallet) and then run live at the $10 floor.
• The runtime owns everything downstream: scheduling (interval_seconds), spawning + supervising + restarting the scanner, validating (signal_data_schema) + de-duplicating the signals you return, sizing & order execution (FEE_OPTIMIZED_LIMIT), slot accounting, risk.guard_rails, the two-phase DSL trailing-stop exits, and crash-safe position reconcile on restart.
• What it does NOT own: partial exits. Every exit the runtime can make (DSL, CLOSE_POSITION) closes the WHOLE position, and edit_position — the only reduce — is blocked to scanners. A rule like "take 25% off at +10% ROE and let the rest run" cannot be authored in a runtime package at all; a scanner that tries raises PermissionError every tick while the log reads as if the rule is working. Details: references/runtime-concepts.md → DSL Exit Engine.

How your code talks to the runtime

The interaction surface is small and one-directional — you read, you return signals, the runtime acts.

• runtime.yaml declares the scanner(s), the action gate, the exit engine, and the risk guard-rails, and passes author tunables down via inputs:. → references/runtime-yaml.md
• scan(inputs, ctx) is the single entry point. inputs is the runtime's inputs: map; ctx gives you:
  • ctx.senpi_mcp.call_tool(name, args) — the Senpi MCP client, read-only (market, account, leaderboard, discovery, strategy_get*, …). It is the only way to fetch data.
  • ctx.state — transactional, runtime-persisted history (last() / append() / len) for dedup, rotation, and first-seen ledgers; advances only on a clean tick.
  • ctx.wallet — the strategy's wallet address.
  • → references/scan-contract.md
• The return value is a list[dict], one per candidate signal (asset, direction, marginPct, leverage, data{}). The runtime validates each data{} against the runtime.yaml's signal_data_schema, then sizes, executes, and manages exits.

Keep the thesis logic in a sibling pure scoring.py (no I/O, no MCP) so it is unit-testable; scan.py does the reads + state, scoring.py does the math.

Runtime commands (essentials)

The plugin registers a senpi command group on the gateway. Deploying a strategy and checking it:

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                           # the job's verified report (read-only); poll it with deploy.py status, below
openclaw senpi runtime list                            # id, source, status ("running — NO ENTRY SCANNERS" = scanners never wired)

Deploy a package through senpi-strategy-ops' deploy.py create <id> --budget <usd>, which resolves the package, runs the structural preflight and drives that same verb. The verb owns the gates — the live-universe check ([E_UNIVERSE_NOT_LIVE], pre-money), the funds preflight, the skillName/skillVersion attribution and the verified tick. runtime create is internal: it installs a runtime and skips every one of those, so it is not the deploy path. Then run python3 deploy.py status until the job is terminal (it calls the gateway directly, ~1 s per read) and relay its report; do NOT re-run create to check on a deploy.

senpi validate is the gate every deploy runs through — it loads the scanners and runs one real tick with no wallet and no funding, and a full unscoped PASS at live depth is what writes the .senpi-proof.json senpi deploy refuses to fund a package without. Run it before deploy, once per instance, pointed at the directory holding that instance's runtime.yaml.

To CHANGE a strategy that is already live → openclaw senpi update, not a delete-and-redeploy. Deleting a runtime abandons its DSL position files, so every open position loses the trailing stop the strategy already promised and its replacement re-adopts from scratch at whatever price it finds. update swaps the components in place and keeps DSL state, scanner stores and action history — no wallet is created, nothing is funded, and no position is closed.

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

It plans by default; --apply is the only way to commit. phase2.tiers is what users call the ratchet; with no open position, the edit plus --apply is the whole change. dsl_preset changes are forward-only — new entries only, while every open position keeps a snapshot of the preset it was opened under (other exit: fields, e.g. order_type, are read live and DO reach open positions). Refused outright, changing nothing: a different strategy.wallet (that is a new deployment, and the old wallet's positions would be left unmanaged), an external scanner renamed or moved (state is keyed by name and position together, and inserting or removing one moves every external scanner below it — appending at the end moves nobody and is allowed), or a changed action_type under a stable name. --apply also needs a passing proof that covers the recipe being applied, so point it at the package DIRECTORY: a recipe handed over as bare text has nothing to verify against and is refused. Exit 2 means the runtime was never touched; exit 1 means an apply was attempted and it may not be where you left it — read the message before retrying.

Saved is not applied. Without --apply, update changes nothing, and only the first line of its output says so — Dry run for <runtime_id> — nothing has been applied. — so never pipe openclaw senpi output through tail or head. A scanner imports scan.py once, when it starts, so a running strategy keeps its old code until --apply restarts its scanners (a crash or a gateway restart would load the edit too, unannounced). senpi validate runs the copy on disk, never the running one, and re-running deploy on a strategy that is already running applies nothing. The edit is live once the apply exits 0 with Updated <runtime_id>. as its first line and no WARNING that its external scanners are NOT running, and the running strategy shows it:

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."

Until both reads show it, tell the user the edit is saved, not applied. What a tick keeps and what discards one: references/scan-contract.md.

Beyond validate, deploy/deploy status, update and runtime list/delete, the CLI exposes the runtime's live state — senpi dsl positions|inspect|closes (the exit engine), senpi action list|inspect|history|decisions (the decision layer), senpi risk (am I allowed to trade, and why not — the daily loss and drawdown halts latch: they stay CLOSED after PnL recovers and survive restarts; a latched halt is the user's call, never clear it or resume entries without their explicit approval → senpi-strategy-author/references/risk-gates.md), senpi audit (backend trade trail with AI reasoning), senpi scanner (per-scanner health, liveness, and a (no signals yet) flag for scanners that run but produce nothing), senpi events/senpi explain <asset> (the local domain-event log — the trade narrative, and one asset's stitched lifecycle), senpi status/senpi state (health — fail-closed: an external scanner never proven by a tick reads unknown, not healthy; non-healthy scanners get their own line with restart count and cause), and senpi guide … (in-shell reference). Full surface with every option → references/runtime-cli.md.

Trade approvals (OpenClaw 10.x). status can also begin with one box-level line, WARNING trade approvals: this box cannot tell chat turns from scheduled runs, so every run is asked, scheduled ones included. Reason: <reason>. It appears whatever the runtimes say, and only on an OpenClaw 10.x box whose config needs a fix (the reason names the setting). Relay it to the user as a box setup problem for Senpi support; nothing on the strategy side changes it. On OpenClaw 5.x there is no such line: every run is asked there by design. --json carries the same fact as approvals.turnClassification (available / unavailable, with reason, and hostLimit: true on 5.x). The WARNING trade approvals line is about the box, not a runtime: it does not mean a runtime is unhealthy, and its absence on 5.x is normal. When the box can classify runs, a trade tool that needs approval asks the user only from a direct chat turn. From a cron or heartbeat run, or another background run, the call is refused before it runs: The trade was not executed: <tool> needs the user's approval, and this scheduled run (cron) has no way to ask for it. …. Nothing was executed. Do what the refusal says: tell the user what you were about to do and that they can ask for it in chat, and do not retry it from that run through another tool or script. A trade the user set to "Always allow" runs in any run kind.

To confirm open positions are actually stop-loss protected (a position with no DSL shows up as an absence in dsl positions, so it's easy to miss) → the verdict procedure in references/dsl-protection-check.md.

The reference set

Read this	For
references/runtime-concepts.md	How the runtime behaves end to end: the runtime pipeline, position_tracker, and the two-phase DSL exit engine
references/runtime-yaml.md	The runtime.yaml schema — every section, the external_scanner fields, the risk guard-rails
references/scan-contract.md	The author contract in depth: scan(inputs, ctx), the ctx surface, the signal shape, and scoring.py
references/runtime-cli.md	The full openclaw senpi … command surface — validate (the pre-deploy gate: flags, depths, exit codes, the proof it records), deploy, runtime, dsl, action, status/state, skills, guide
references/dsl-protection-check.md	Verify open positions are DSL-protected — the PROTECTED / UNPROTECTED / STOP-NOT-ON-VENUE verdict + the open-vs-tracked reconciliation

Package naming (load-bearing)

The runtime package is @senpi-ai/runtime (with -ai) — the one users install on their hosts. Always write it with the -ai.