@coinrithm/mcp-trading 0.1.7 → 0.2.0

package/dist/agent/runner.js

@@ -0,0 +1,197 @@
+// The execution loop: observe -> decide (BYO model) -> validate -> act. v1
+// futures only. Dry-run never writes. Live uses idempotency keys + agentTrace
+// and exports run evidence. The client + provider are injected so the loop is
+// fully unit-testable with no network and no model calls.
+import { observe } from "./observe.js";
+import { buildSystemPrompt, buildUserPrompt } from "./prompt.js";
+import { parseDecision } from "./decision.js";
+import { validateAction } from "./decisionValidator.js";
+import { fetchQuote, executeAction } from "./act.js";
+import { makeDecisionId, makeTrace, exportRunEvidence } from "./runEvidence.js";
+import { rollDay, checkKillSwitch, accrueRealized, saveState } from "./state.js";
+import { asObj, asNum, asStr } from "./extract.js";
+import { parseCadenceMs, sleep } from "./util.js";
+// A stable idempotency-key component per distinct intent (so a lost response
+// replays rather than re-trades, but a genuinely new intent gets a new key).
+function intentKeyOf(action) {
+    if (action.type === "futures_open") {
+        return `open:${action.symbol.toUpperCase()}:${action.side}:${action.leverage}:${action.marginMusd}`;
+    }
+    if (action.type === "futures_close") {
+        return `close:${action.positionId}:${action.fraction ?? "full"}`;
+    }
+    if (action.type === "futures_set_sltp") {
+        return `sltp:${action.positionId}`;
+    }
+    return `other:${action.type}`; // unreachable: only futures actions are executed
+}
+export async function runCycle(deps) {
+    const { client, provider, spec, mergedProse, state, live, stateFile } = deps;
+    const log = deps.log ?? (() => { });
+    state.cyclesRun += 1;
+    rollDay(state);
+    // Kill-switch pre-check: a disabled agent never observes, decides, or acts.
+    const tripped = checkKillSwitch(spec, state);
+    if (tripped) {
+        state.disabled = true;
+        state.disabledReason = tripped;
+        saveState(stateFile, state);
+        log(`disabled: ${tripped}`);
+        return { decision: "skip", planned: [], disabled: true, disabledReason: tripped, live };
+    }
+    const runId = state.runId;
+    const decisionId = makeDecisionId(state.cyclesRun);
+    const baseTrace = makeTrace(runId, decisionId, spec);
+    // OBSERVE
+    const obs = await observe(client, spec, state, baseTrace);
+    const observation = obs.observation;
+    accrueRealized(state, observation.newClosedTrades);
+    state.cursor = observation.syncCursor;
+    for (const t of observation.newClosedTrades) {
+        state.seen.push(`${asStr(asObj(t).venue) ?? "futures"}:${asNum(asObj(t).id) ?? String(asObj(t).id)}`);
+    }
+    state.seen = state.seen.slice(-500);
+    // Equity-aware drawdown: open mark-to-market losses trip the kill-switch too,
+    // not only realized losses.
+    const unrealized = observation.openPositions.reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0);
+    if (spec.killSwitch.maxDrawdownMusd > 0 &&
+        state.peakRealizedMusd - (state.realizedPnlMusd + unrealized) >= spec.killSwitch.maxDrawdownMusd) {
+        state.disabled = true;
+        state.disabledReason = `equity drawdown >= ${spec.killSwitch.maxDrawdownMusd}`;
+        saveState(stateFile, state);
+        log(`disabled: ${state.disabledReason}`);
+        return { decision: "skip", planned: [], disabled: true, disabledReason: state.disabledReason, live };
+    }
+    if (obs.skip) {
+        state.consecutiveRejectCycles += 1;
+        saveState(stateFile, state);
+        log(`skip: ${obs.skip}`);
+        return { decision: "skip", skipReason: obs.skip, planned: [], live };
+    }
+    // DECIDE
+    const res = await provider.decide({
+        system: buildSystemPrompt(spec, mergedProse),
+        user: buildUserPrompt(observation),
+    });
+    if (!res.ok) {
+        state.consecutiveModelFailures += 1;
+        saveState(stateFile, state);
+        log(`model error: ${res.error}`);
+        return { decision: "skip", skipReason: `model error: ${res.error}`, planned: [], modelFailed: true, live };
+    }
+    const parsed = parseDecision(res.text);
+    if (!parsed.ok) {
+        state.consecutiveModelFailures += 1;
+        saveState(stateFile, state);
+        log(`model output invalid: ${parsed.error}`);
+        return { decision: "skip", skipReason: `model output invalid: ${parsed.error}`, planned: [], modelFailed: true, live };
+    }
+    state.consecutiveModelFailures = 0;
+    const decision = parsed.decision;
+    if (decision.decision === "skip" || decision.actions.length === 0) {
+        state.consecutiveRejectCycles += 1;
+        saveState(stateFile, state);
+        log(`model chose skip${decision.reason ? `: ${decision.reason}` : ""}`);
+        return { decision: "skip", skipReason: decision.reason ?? "model chose skip", planned: [], live };
+    }
+    // VALIDATE (+ ACT when live). Quote evidence is fetched by the runner.
+    const planned = [];
+    let writesThisCycle = 0;
+    let openCount = observation.openPositions.length;
+    // RUNNING totals so multiple opens in one cycle accumulate correctly.
+    let openMarginMusd = observation.openPositions
+        .filter((p) => p.venue === "futures")
+        .reduce((s, p) => s + (p.marginMusd ?? 0), 0);
+    let cashAvailableMusd = observation.cashAvailableMusd;
+    const realizedLossTodayMusd = Math.max(0, -state.realizedPnlTodayMusd);
+    const targetedPositionIds = [];
+    let anyAccepted = false;
+    let anyExecuted = false;
+    let anyExecFailed = false;
+    for (const action of decision.actions) {
+        const quote = await fetchQuote(client, action, observation, baseTrace);
+        const ctx = {
+            spec,
+            observation,
+            quote,
+            writesThisCycle,
+            writesToday: state.writesToday,
+            openCount,
+            cashAvailableMusd,
+            openMarginMusd,
+            realizedLossTodayMusd,
+            targetedPositionIds,
+        };
+        const v = validateAction(action, ctx);
+        if (!v.valid) {
+            planned.push({ action, accepted: false, code: v.code, reason: v.reason, quote });
+            log(`reject ${action.type}: ${v.code} (${v.reason})`);
+            continue;
+        }
+        anyAccepted = true;
+        if (action.type === "futures_close" || action.type === "futures_set_sltp") {
+            targetedPositionIds.push(action.positionId);
+        }
+        if (!live) {
+            planned.push({ action, accepted: true, quote, executed: false });
+            log(`DRY-RUN: would ${action.type}`);
+            continue;
+        }
+        // Deterministic idempotency key: stable per intent, advanced only on
+        // confirmed success — a lost response replays, a new intent gets a new key.
+        const intentKey = intentKeyOf(action);
+        const seq = state.intentSeq[intentKey] ?? 0;
+        const idem = `${runId}:${intentKey}:${seq}`;
+        const meta = action;
+        const trace = makeTrace(runId, decisionId, spec, meta.confidence, meta.rationaleSummary);
+        const r = await executeAction(client, action, observation, trace, idem);
+        planned.push({ action, accepted: true, quote, executed: r.ok, result: r.data });
+        if (r.ok) {
+            anyExecuted = true;
+            state.intentSeq[intentKey] = seq + 1;
+            writesThisCycle += 1;
+            state.writesToday += 1;
+            if (action.type === "futures_open") {
+                openCount += 1;
+                openMarginMusd += action.marginMusd;
+                if (cashAvailableMusd != null)
+                    cashAvailableMusd -= action.marginMusd;
+            }
+        }
+        else {
+            anyExecFailed = true;
+        }
+        log(`${r.ok ? "executed" : "FAILED"} ${action.type} (HTTP ${r.status})`);
+    }
+    // Reset the reject kill-switch only on real PROGRESS: an accepted-but-FAILED
+    // live write is not progress, or a persistently failing live agent would
+    // never trip the kill-switch.
+    const progressed = live ? anyExecuted : anyAccepted;
+    state.consecutiveRejectCycles = progressed ? 0 : state.consecutiveRejectCycles + 1;
+    state.consecutiveExecFailures = anyExecFailed && !anyExecuted ? state.consecutiveExecFailures + 1 : 0;
+    state.rateLimitHits = client.rateLimitHits ?? state.rateLimitHits;
+    saveState(stateFile, state);
+    if (live && anyExecuted)
+        await exportRunEvidence(client, runId);
+    return { decision: "act", planned, live };
+}
+export async function runLoop(deps, opts = {}) {
+    const results = [];
+    const cadenceMs = parseCadenceMs(deps.spec.trigger.cadence) ?? 3_600_000;
+    const log = deps.log ?? (() => { });
+    let cycles = 0;
+    for (;;) {
+        const r = await runCycle(deps);
+        results.push(r);
+        cycles += 1;
+        if (r.disabled)
+            break;
+        if (opts.once)
+            break;
+        if (opts.maxCycles && cycles >= opts.maxCycles)
+            break;
+        log(`sleeping ${Math.round(cadenceMs / 1000)}s until next cycle`);
+        await sleep(cadenceMs);
+    }
+    return results;
+}

package/dist/agent/skill.js

@@ -0,0 +1,132 @@
+import { readFileSync } from "node:fs";
+import { parseFrontmatter } from "./frontmatter.js";
+import { VENUES, PROVIDERS, ALLOWED_CAPABILITIES, } from "./types.js";
+import { resolveAgent, ResolveError } from "./resolve.js";
+import { strictLint } from "./strictLint.js";
+// Safe defaults for the OPTIONAL policy blocks. A minimal self-host skill
+// (name/description/spec/trigger/model/venues/risk) runs under these. Hosted
+// mode requires them to be explicit (see skillValidator).
+const DEFAULT_LIMITS = {
+    maxTradesPerDay: 20,
+    maxWritesPerCycle: 2,
+    maxDailyLossMusd: 5_000,
+    maxOpenMarginMusd: 5_000,
+};
+const DEFAULT_ABSTENTION = {
+    onStaleData: true,
+    onWeakSignal: true,
+    onMissingQuote: true,
+    onInsufficientBalance: true,
+    minConfidence: 0,
+};
+const DEFAULT_SYNC = { requirePollBeforeWrite: true };
+const DEFAULT_KILLSWITCH = {
+    maxDrawdownMusd: 0, // 0 = disabled
+    maxConsecutiveRejects: 0, // 0 = disabled
+    maxConsecutiveModelFailures: 5,
+    onRateLimitPressure: true,
+};
+const num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+const bool = (v, fallback) => typeof v === "boolean" ? v : fallback;
+const strArr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+const obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v)
+    ? v
+    : {};
+function buildObjective(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const o = raw;
+    if (typeof o.primary !== "string")
+        return undefined;
+    return {
+        primary: o.primary,
+        secondary: strArr(o.secondary),
+        horizon: typeof o.horizon === "string" ? o.horizon : undefined,
+    };
+}
+function buildModel(raw) {
+    if (raw === undefined)
+        return undefined;
+    const m = obj(raw);
+    return {
+        provider: (PROVIDERS.includes(m.provider)
+            ? m.provider
+            : "openai-compatible"),
+        name: typeof m.name === "string" ? m.name : "",
+        baseUrl: typeof m.baseUrl === "string" ? m.baseUrl : undefined,
+    };
+}
+// Coerce raw frontmatter into a best-effort AgentSpec. This NEVER throws on bad
+// values — it fills in what it can and lets validateSkill report problems
+// against the raw frontmatter. The runner only proceeds when validation passes.
+export function buildSpec(raw) {
+    const trigger = obj(raw.trigger);
+    const risk = obj(raw.risk);
+    const limits = obj(raw.limits);
+    const abst = obj(raw.abstention);
+    const sync = obj(raw.sync);
+    const ks = obj(raw.killSwitch);
+    const venues = strArr(raw.venues).filter((v) => VENUES.includes(v));
+    return {
+        name: typeof raw.name === "string" ? raw.name : "",
+        description: typeof raw.description === "string" ? raw.description : "",
+        spec: typeof raw.spec === "string" ? raw.spec : "",
+        trigger: {
+            cadence: typeof trigger.cadence === "string" ? trigger.cadence : "",
+            timezone: typeof trigger.timezone === "string" ? trigger.timezone : undefined,
+        },
+        model: buildModel(raw.model),
+        venues,
+        risk: {
+            maxLeverage: num(risk.maxLeverage, 1),
+            perTradeMarginMusd: num(risk.perTradeMarginMusd, 0),
+            maxConcurrentPositions: num(risk.maxConcurrentPositions, 0),
+            requireStopLoss: bool(risk.requireStopLoss, true),
+            watchlist: strArr(risk.watchlist),
+        },
+        limits: {
+            maxTradesPerDay: num(limits.maxTradesPerDay, DEFAULT_LIMITS.maxTradesPerDay),
+            maxWritesPerCycle: num(limits.maxWritesPerCycle, DEFAULT_LIMITS.maxWritesPerCycle),
+            maxDailyLossMusd: num(limits.maxDailyLossMusd, DEFAULT_LIMITS.maxDailyLossMusd),
+            maxOpenMarginMusd: num(limits.maxOpenMarginMusd, DEFAULT_LIMITS.maxOpenMarginMusd),
+        },
+        abstention: {
+            onStaleData: bool(abst.onStaleData, DEFAULT_ABSTENTION.onStaleData),
+            onWeakSignal: bool(abst.onWeakSignal, DEFAULT_ABSTENTION.onWeakSignal),
+            onMissingQuote: bool(abst.onMissingQuote, DEFAULT_ABSTENTION.onMissingQuote),
+            onInsufficientBalance: bool(abst.onInsufficientBalance, DEFAULT_ABSTENTION.onInsufficientBalance),
+            minConfidence: num(abst.minConfidence, DEFAULT_ABSTENTION.minConfidence),
+        },
+        sync: {
+            requirePollBeforeWrite: bool(sync.requirePollBeforeWrite, DEFAULT_SYNC.requirePollBeforeWrite),
+        },
+        killSwitch: {
+            maxDrawdownMusd: num(ks.maxDrawdownMusd, DEFAULT_KILLSWITCH.maxDrawdownMusd),
+            maxConsecutiveRejects: num(ks.maxConsecutiveRejects, DEFAULT_KILLSWITCH.maxConsecutiveRejects),
+            maxConsecutiveModelFailures: num(ks.maxConsecutiveModelFailures, DEFAULT_KILLSWITCH.maxConsecutiveModelFailures),
+            onRateLimitPressure: bool(ks.onRateLimitPressure, DEFAULT_KILLSWITCH.onRateLimitPressure),
+        },
+        objective: buildObjective(raw.objective),
+        capabilities: strArr(raw.capabilities).filter((c) => ALLOWED_CAPABILITIES.includes(c)),
+    };
+}
+export function parseSkill(text) {
+    const { data, body } = parseFrontmatter(text);
+    return { spec: buildSpec(data), body, raw: data };
+}
+export function loadSkill(path) {
+    return parseSkill(readFileSync(path, "utf8"));
+}
+// Compile an agent (single file OR decomposed folder) into a spec + the prose
+// the LLM reads. Fail-closed: resolveAgent() throws on any structural/secret
+// problem. In hosted mode the strict key/enum lint is ALSO fatal (no silent
+// coercion of a typo'd knob); self-host returns lint as advisory issues.
+export function loadAgent(inputPath, mode = "self-host") {
+    const resolved = resolveAgent(inputPath);
+    const raw = resolved.rawFrontmatter;
+    const lint = strictLint(raw);
+    if (mode === "hosted" && lint.length)
+        throw new ResolveError(lint);
+    const spec = buildSpec(raw);
+    return { resolved, spec, body: resolved.mergedProse, raw, lint };
+}

package/dist/agent/skillValidator.js

@@ -0,0 +1,123 @@
+import { fail, VENUES, PROVIDERS, SPEC_VERSION, OBJECTIVE_PRIMARIES, ALLOWED_CAPABILITIES, } from "./types.js";
+import { parseCadenceMs, scanForSecrets } from "./util.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isPosNum = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
+export function validateSkill(parsed, mode = "self-host") {
+    const raw = parsed.raw;
+    const issues = [];
+    const add = (code, reason) => issues.push(fail(code, reason));
+    // Secrets must NEVER live in a committable skill file.
+    for (const finding of scanForSecrets(raw))
+        add("skill_secret", finding);
+    // Identity
+    if (typeof raw.name !== "string" || !raw.name.trim())
+        add("skill_name", "name is required (string)");
+    if (typeof raw.description !== "string" || !raw.description.trim())
+        add("skill_description", "description is required (string)");
+    if (raw.spec !== SPEC_VERSION)
+        add("skill_spec_version", `spec must be "${SPEC_VERSION}"`);
+    // Trigger
+    if (!isObj(raw.trigger)) {
+        add("skill_trigger", "trigger block is required");
+    }
+    else if (parseCadenceMs(raw.trigger.cadence) === null) {
+        add("skill_cadence", `trigger.cadence must look like "15m" / "1h" / "4h" (got ${JSON.stringify(raw.trigger.cadence)})`);
+    }
+    // Venues
+    if (!Array.isArray(raw.venues) || raw.venues.length === 0) {
+        add("skill_venues", "venues must be a non-empty list");
+    }
+    else {
+        for (const v of raw.venues) {
+            if (!VENUES.includes(v))
+                add("skill_venue_unknown", `unknown venue "${String(v)}" (allowed: ${VENUES.join(", ")})`);
+        }
+    }
+    // Risk — always required
+    if (!isObj(raw.risk)) {
+        add("skill_risk", "risk block is required (the caps the agent runs under)");
+    }
+    else {
+        const r = raw.risk;
+        if (!isPosNum(r.maxLeverage))
+            add("skill_risk_leverage", "risk.maxLeverage must be a positive number");
+        else if (r.maxLeverage > 20)
+            add("skill_risk_leverage_cap", "risk.maxLeverage cannot exceed the server cap of 20");
+        if (!isPosNum(r.perTradeMarginMusd))
+            add("skill_risk_margin", "risk.perTradeMarginMusd must be a positive number");
+        if (!isPosNum(r.maxConcurrentPositions))
+            add("skill_risk_positions", "risk.maxConcurrentPositions must be a positive number");
+        if (typeof r.requireStopLoss !== "boolean")
+            add("skill_risk_sl", "risk.requireStopLoss must be true or false");
+        if (!Array.isArray(r.watchlist) || r.watchlist.length === 0)
+            add("skill_risk_watchlist", "risk.watchlist must be a non-empty list of symbols");
+    }
+    // Model
+    if (raw.model === undefined) {
+        if (mode === "self-host")
+            add("skill_model_required", "model is required for self-host (no hosted free-tier locally). Set model.provider + model.name.");
+    }
+    else if (!isObj(raw.model)) {
+        add("skill_model", "model must be an object with provider + name");
+    }
+    else {
+        if (!PROVIDERS.includes(raw.model.provider))
+            add("skill_model_provider", `model.provider must be one of: ${PROVIDERS.join(", ")}`);
+        if (typeof raw.model.name !== "string" || !raw.model.name.trim())
+            add("skill_model_name", "model.name is required");
+        if (raw.model.provider === "openai-compatible" &&
+            (typeof raw.model.baseUrl !== "string" || !raw.model.baseUrl.trim()))
+            add("skill_model_baseurl", "model.baseUrl is required for provider 'openai-compatible'");
+    }
+    // objective (optional)
+    if (raw.objective !== undefined) {
+        if (!isObj(raw.objective)) {
+            add("skill_objective", "objective must be an object");
+        }
+        else if (typeof raw.objective.primary !== "string" ||
+            !OBJECTIVE_PRIMARIES.includes(raw.objective.primary)) {
+            add("skill_objective_primary", `objective.primary must be one of: ${OBJECTIVE_PRIMARIES.join(", ")}`);
+        }
+    }
+    // capabilities (optional, opt-in, reserved for a later slice)
+    if (raw.capabilities !== undefined) {
+        if (!Array.isArray(raw.capabilities)) {
+            add("skill_capabilities", "capabilities must be a list");
+        }
+        else {
+            for (const c of raw.capabilities) {
+                if (!ALLOWED_CAPABILITIES.includes(c)) {
+                    add("skill_capability_unknown", `unknown capability "${String(c)}" (allowed: ${ALLOWED_CAPABILITIES.join(", ")})`);
+                }
+            }
+        }
+    }
+    // Hosted mode: the safety policy blocks must be explicit.
+    if (mode === "hosted") {
+        if (!isObj(raw.limits)) {
+            add("skill_limits_required", "limits block is required in hosted mode");
+        }
+        else {
+            const l = raw.limits;
+            if (!isPosNum(l.maxTradesPerDay))
+                add("skill_limits_trades", "limits.maxTradesPerDay must be a positive number");
+            if (!isPosNum(l.maxWritesPerCycle))
+                add("skill_limits_writes", "limits.maxWritesPerCycle must be a positive number");
+            if (!isPosNum(l.maxDailyLossMusd))
+                add("skill_limits_loss", "limits.maxDailyLossMusd must be a positive number");
+            if (!isPosNum(l.maxOpenMarginMusd))
+                add("skill_limits_open", "limits.maxOpenMarginMusd must be a positive number");
+        }
+        if (!isObj(raw.abstention))
+            add("skill_abstention_required", "abstention block is required in hosted mode");
+        if (!isObj(raw.sync)) {
+            add("skill_sync_required", "sync block is required in hosted mode");
+        }
+        else if (typeof raw.sync.requirePollBeforeWrite !== "boolean") {
+            add("skill_sync_poll", "sync.requirePollBeforeWrite must be true or false");
+        }
+        if (!isObj(raw.killSwitch))
+            add("skill_killswitch_required", "killSwitch block is required in hosted mode");
+    }
+    return { valid: issues.length === 0, issues };
+}

package/dist/agent/state.js

@@ -0,0 +1,94 @@
+// Local run state: the cursor, dedupe set, daily counters, and the kill-switch
+// inputs. Persisted to a JSON file so a re-run resumes where it left off.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { dayKey } from "./util.js";
+import { asObj, asNum } from "./extract.js";
+// Disable after this many 429s in a session when killSwitch.onRateLimitPressure.
+const RATE_LIMIT_PRESSURE_THRESHOLD = 5;
+export function newState(runId) {
+    return {
+        runId,
+        cyclesRun: 0,
+        writesToday: 0,
+        realizedPnlMusd: 0,
+        peakRealizedMusd: 0,
+        consecutiveRejectCycles: 0,
+        consecutiveModelFailures: 0,
+        rateLimitHits: 0,
+        disabled: false,
+        dayKey: dayKey(),
+        cursor: null,
+        seen: [],
+        realizedPnlTodayMusd: 0,
+        consecutiveExecFailures: 0,
+        intentSeq: {},
+    };
+}
+// A corrupt EXISTING state file is FAIL-CLOSED: we refuse to run rather than
+// silently reset and (e.g.) re-enable a kill-switched agent or zero the daily
+// counters. A missing file is fine (fresh start).
+export function loadState(file, runId) {
+    if (file && existsSync(file)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch (e) {
+            throw new Error(`run state file is corrupt (${file}): ${e instanceof Error ? e.message : String(e)} — fix or delete it before running`);
+        }
+        const base = newState(parsed.runId ?? runId);
+        return rollDay({
+            ...base,
+            ...parsed,
+            seen: Array.isArray(parsed.seen) ? parsed.seen : [],
+            intentSeq: parsed.intentSeq && typeof parsed.intentSeq === "object" ? parsed.intentSeq : {},
+        });
+    }
+    return newState(runId);
+}
+export function saveState(file, state) {
+    if (!file)
+        return;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(state, null, 2), "utf8");
+}
+export function rollDay(state) {
+    const today = dayKey();
+    if (state.dayKey !== today) {
+        state.dayKey = today;
+        state.writesToday = 0;
+        state.realizedPnlTodayMusd = 0;
+    }
+    return state;
+}
+// Accrue realized PnL from newly-closed trades into both the session total (for
+// drawdown) and today's total (for the daily-loss cap). Dedupe by the caller.
+export function accrueRealized(state, closedTrades) {
+    for (const t of closedTrades) {
+        const pnl = asNum(asObj(t).realizedPnlMusd);
+        if (pnl != null) {
+            state.realizedPnlMusd += pnl;
+            state.realizedPnlTodayMusd += pnl;
+        }
+    }
+    if (state.realizedPnlMusd > state.peakRealizedMusd)
+        state.peakRealizedMusd = state.realizedPnlMusd;
+}
+// Returns a disable reason if any kill-switch condition is tripped, else null.
+export function checkKillSwitch(spec, state) {
+    const ks = spec.killSwitch;
+    if (ks.maxConsecutiveModelFailures > 0 && state.consecutiveModelFailures >= ks.maxConsecutiveModelFailures) {
+        return `consecutive model failures ${state.consecutiveModelFailures} >= ${ks.maxConsecutiveModelFailures}`;
+    }
+    if (ks.maxConsecutiveRejects > 0 && state.consecutiveRejectCycles >= ks.maxConsecutiveRejects) {
+        return `consecutive reject cycles ${state.consecutiveRejectCycles} >= ${ks.maxConsecutiveRejects}`;
+    }
+    if (ks.maxDrawdownMusd > 0 && state.peakRealizedMusd - state.realizedPnlMusd >= ks.maxDrawdownMusd) {
+        return `drawdown ${(state.peakRealizedMusd - state.realizedPnlMusd).toFixed(2)} >= ${ks.maxDrawdownMusd}`;
+    }
+    if (ks.onRateLimitPressure && state.rateLimitHits >= RATE_LIMIT_PRESSURE_THRESHOLD) {
+        return `rate-limit pressure: ${state.rateLimitHits} 429s this session`;
+    }
+    return null;
+}