@coinrithm/mcp-trading 0.1.8 → 0.3.0

package/dist/agent/runner.d.ts

@@ -0,0 +1,19 @@
+import { CoinRithmClient } from "./client.js";
+import { Provider } from "./providers.js";
+import { AgentSpec, RunState, CycleResult } from "./types.js";
+export interface RunnerDeps {
+    client: CoinRithmClient;
+    provider: Provider;
+    spec: AgentSpec;
+    mergedProse: string;
+    state: RunState;
+    live: boolean;
+    stateFile?: string;
+    log?: (line: string) => void;
+}
+export declare function runCycle(deps: RunnerDeps): Promise<CycleResult>;
+export interface LoopOptions {
+    once?: boolean;
+    maxCycles?: number;
+}
+export declare function runLoop(deps: RunnerDeps, opts?: LoopOptions): Promise<CycleResult[]>;

package/dist/agent/runner.js

@@ -0,0 +1,280 @@
+// The execution loop: observe -> decide (BYO model) -> validate -> act across
+// spot, futures, and prediction markets. 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/model calls.
+import { spotBuyCost, } from "./types.js";
+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}`;
+    }
+    if (action.type === "spot_order") {
+        return `spot:${action.symbol.toUpperCase()}:${action.side}:${action.orderType}:${action.quantity}:${action.limitPrice ?? ""}:${action.stopPrice ?? ""}`;
+    }
+    if (action.type === "spot_cancel") {
+        return `cancel:${action.orderId}`;
+    }
+    if (action.type === "pm_open") {
+        return `pm:${action.source.toLowerCase()}:${action.slug.toLowerCase()}:${action.outcomeExternalMarketId}:${action.stakeMusd}`;
+    }
+    return "other"; // unreachable: every action type is handled above
+}
+// Estimated cash a successful action consumes (for the running-cash guard):
+// futures margin, spot buy notional, or a PM stake. Closes/cancels/sells free
+// cash or are neutral, so they consume nothing here. Spot buys use the SAME
+// `spotBuyCost` helper the validator gates on, so the gate and this decrement
+// never diverge. The `?? 0` is unreachable for an EXECUTED buy: the validator
+// fails closed (missing_quote_price) on any buy whose cost can't be sized, so
+// nothing with an undefined cost ever reaches execution to be decremented.
+function cashConsumed(action, quote) {
+    if (action.type === "futures_open")
+        return action.marginMusd;
+    if (action.type === "pm_open")
+        return action.stakeMusd;
+    if (action.type === "spot_order" && action.side === "buy") {
+        return spotBuyCost(action, quote) ?? 0;
+    }
+    return 0;
+}
+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 = [];
+    const targetedOrderIds = [];
+    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,
+            // Inherit the decision-level confidence so the per-action abstention gate
+            // doesn't reject a model that reports conviction on the decision (the
+            // output contract) rather than on each action.
+            decisionConfidence: decision.confidence,
+            observation,
+            quote,
+            writesThisCycle,
+            writesToday: state.writesToday,
+            openCount,
+            cashAvailableMusd,
+            openMarginMusd,
+            realizedLossTodayMusd,
+            targetedPositionIds,
+            targetedOrderIds,
+        };
+        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 (action.type === "spot_cancel") {
+            targetedOrderIds.push(action.orderId);
+        }
+        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 ?? decision.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;
+            }
+            // Decrement running cash by what this action consumed (futures margin /
+            // spot buy notional / PM stake) so a later action this cycle sees it spent.
+            if (cashAvailableMusd != null)
+                cashAvailableMusd -= cashConsumed(action, quote);
+        }
+        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.d.ts

@@ -0,0 +1,12 @@
+import { AgentSpec, ParsedSkill, ResolvedAgent, ResolveIssue } from "./types.js";
+export declare function buildSpec(raw: Record<string, unknown>): AgentSpec;
+export declare function parseSkill(text: string): ParsedSkill;
+export declare function loadSkill(path: string): ParsedSkill;
+export interface LoadedAgent {
+    resolved: ResolvedAgent;
+    spec: AgentSpec;
+    body: string;
+    raw: Record<string, unknown>;
+    lint: ResolveIssue[];
+}
+export declare function loadAgent(inputPath: string, mode?: "self-host" | "hosted"): LoadedAgent;

package/dist/agent/skill.js

@@ -0,0 +1,136 @@
+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";
+import { checkCapabilityDrift } from "./capabilityGuard.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),
+            blocklist: strArr(risk.blocklist),
+        },
+        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 spec = buildSpec(raw);
+    // strictLint = frontmatter keys/enums; capability drift = prose references to
+    // venues/actions/caps the runner (or this agent's venues) does not support.
+    const lint = [...strictLint(raw), ...checkCapabilityDrift(resolved, spec)];
+    if (mode === "hosted" && lint.length)
+        throw new ResolveError(lint);
+    return { resolved, spec, body: resolved.mergedProse, raw, lint };
+}

package/dist/agent/skillValidator.d.ts

@@ -0,0 +1,7 @@
+import { ParsedSkill, ValidationResult } from "./types.js";
+export type SkillValidationMode = "self-host" | "hosted";
+export interface SkillValidation {
+    valid: boolean;
+    issues: ValidationResult[];
+}
+export declare function validateSkill(parsed: ParsedSkill, mode?: SkillValidationMode): SkillValidation;

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.d.ts

@@ -0,0 +1,7 @@
+import { RunState, AgentSpec } from "./types.js";
+export declare function newState(runId: string): RunState;
+export declare function loadState(file: string | undefined, runId: string): RunState;
+export declare function saveState(file: string | undefined, state: RunState): void;
+export declare function rollDay(state: RunState): RunState;
+export declare function accrueRealized(state: RunState, closedTrades: Record<string, unknown>[]): void;
+export declare function checkKillSwitch(spec: AgentSpec, state: RunState): string | null;