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.

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                           # poll until terminal; the verified report (read-only)
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.

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. 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), 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.

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

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.