@coinrithm/mcp-trading 0.1.8 → 0.3.0

package/dist/agent/indicators.js

@@ -0,0 +1,135 @@
+// Deterministic technical-indicator math — pure functions over OHLC candles.
+//
+// Probe-First note: this module is JUST math (no network). It is the
+// runner-computed half of the `indicators` capability (types.ts) — an agent
+// that declares it gets compact, model-friendly signal (RSI/EMA/ATR/Bollinger/
+// breakout levels) instead of raw bars the free-tier brain cannot reason over.
+// Wiring observe() to FETCH the candles is gated on a live probe of
+// GET /api/agent/market/:coinId/candles (see DECISIONS D16); the math here is
+// independently verifiable and shipped ahead of that.
+//
+// Every function returns null when there are too few candles, so callers can
+// omit an indicator from the observation rather than emit a misleading number.
+const closesOf = (c) => c.map((x) => x.close);
+const finite = (n) => Number.isFinite(n);
+// Simple moving average of the last `period` values.
+export function sma(values, period) {
+    if (period <= 0 || values.length < period)
+        return null;
+    const slice = values.slice(-period);
+    const sum = slice.reduce((a, b) => a + b, 0);
+    return finite(sum) ? sum / period : null;
+}
+// Exponential moving average, seeded with the SMA of the first `period` values
+// (the standard, deterministic seeding).
+export function ema(values, period) {
+    if (period <= 0 || values.length < period)
+        return null;
+    const k = 2 / (period + 1);
+    let prev = values.slice(0, period).reduce((a, b) => a + b, 0) / period;
+    for (let i = period; i < values.length; i++) {
+        prev = values[i] * k + prev * (1 - k);
+    }
+    return finite(prev) ? prev : null;
+}
+// Wilder's RSI over `period` (default 14). 100 = only gains, 0 = only losses.
+export function rsi(closes, period = 14) {
+    if (period <= 0 || closes.length < period + 1)
+        return null;
+    let gain = 0;
+    let loss = 0;
+    for (let i = 1; i <= period; i++) {
+        const ch = closes[i] - closes[i - 1];
+        if (ch >= 0)
+            gain += ch;
+        else
+            loss -= ch;
+    }
+    let avgGain = gain / period;
+    let avgLoss = loss / period;
+    for (let i = period + 1; i < closes.length; i++) {
+        const ch = closes[i] - closes[i - 1];
+        const g = ch >= 0 ? ch : 0;
+        const l = ch < 0 ? -ch : 0;
+        avgGain = (avgGain * (period - 1) + g) / period;
+        avgLoss = (avgLoss * (period - 1) + l) / period;
+    }
+    if (avgLoss === 0)
+        return avgGain === 0 ? 50 : 100;
+    const rs = avgGain / avgLoss;
+    return 100 - 100 / (1 + rs);
+}
+// Wilder's Average True Range over `period` (default 14) — a volatility gauge.
+export function atr(candles, period = 14) {
+    if (period <= 0 || candles.length < period + 1)
+        return null;
+    const tr = [];
+    for (let i = 1; i < candles.length; i++) {
+        const h = candles[i].high;
+        const l = candles[i].low;
+        const pc = candles[i - 1].close;
+        tr.push(Math.max(h - l, Math.abs(h - pc), Math.abs(l - pc)));
+    }
+    if (tr.length < period)
+        return null;
+    let prev = tr.slice(0, period).reduce((a, b) => a + b, 0) / period;
+    for (let i = period; i < tr.length; i++) {
+        prev = (prev * (period - 1) + tr[i]) / period;
+    }
+    return finite(prev) ? prev : null;
+}
+// Bollinger bands: SMA(period) ± mult·stddev over the last `period` closes.
+export function bollinger(closes, period = 20, mult = 2) {
+    if (period <= 0 || closes.length < period)
+        return null;
+    const slice = closes.slice(-period);
+    const mid = slice.reduce((a, b) => a + b, 0) / period;
+    const variance = slice.reduce((a, b) => a + (b - mid) ** 2, 0) / period;
+    const sd = Math.sqrt(variance);
+    if (!finite(mid) || !finite(sd))
+        return null;
+    return { upper: mid + mult * sd, mid, lower: mid - mult * sd };
+}
+// Highest high / lowest low over the last `lookback` candles (breakout levels).
+export function recentHighLow(candles, lookback) {
+    if (lookback <= 0 || candles.length === 0)
+        return null;
+    const slice = candles.slice(-lookback);
+    let high = -Infinity;
+    let low = Infinity;
+    for (const c of slice) {
+        if (c.high > high)
+            high = c.high;
+        if (c.low < low)
+            low = c.low;
+    }
+    return finite(high) && finite(low) ? { high, low } : null;
+}
+// Compute the compact indicator bundle the runner injects into the observation
+// for an agent that declared the `indicators` capability. The breakout flags
+// compare the latest close against the high/low of the PRECEDING window (so a
+// candle closing at a new 20-bar high reads as a breakout, not a tautology).
+export function computeIndicators(candles, opts = {}) {
+    if (candles.length === 0)
+        return null;
+    const closes = closesOf(candles);
+    const close = closes[closes.length - 1];
+    const { rsiPeriod = 14, emaFast = 20, emaSlow = 50, atrPeriod = 14, bbPeriod = 20, breakoutLookback = 20, } = opts;
+    const ema20 = ema(closes, emaFast);
+    const ema50 = ema(closes, emaSlow);
+    // Breakout vs the window BEFORE the latest candle (exclude the current bar).
+    const prior = recentHighLow(candles.slice(0, -1), breakoutLookback);
+    return {
+        asOfClose: close,
+        rsi14: rsi(closes, rsiPeriod),
+        ema20,
+        ema50,
+        atr14: atr(candles, atrPeriod),
+        bollinger: bollinger(closes, bbPeriod),
+        recent20: recentHighLow(candles, breakoutLookback),
+        aboveEma20: ema20 == null ? null : close > ema20,
+        ema20AboveEma50: ema20 == null || ema50 == null ? null : ema20 > ema50,
+        brokeRecentHigh: prior == null ? null : close >= prior.high,
+        brokeRecentLow: prior == null ? null : close <= prior.low,
+    };
+}

package/dist/agent/manifest.d.ts

@@ -0,0 +1,15 @@
+import { AgentSpec, ResolvedAgent, Provenance } from "./types.js";
+export interface AgentManifest {
+    schema: string;
+    spec: string;
+    resolverVersion: string;
+    runnerVersion: string;
+    resolvedConfig: Record<string, unknown>;
+    resolvedSpec: AgentSpec;
+    provenance: Provenance;
+    contentHashes: Record<string, string>;
+    configHash: string;
+}
+export declare function buildManifest(resolved: ResolvedAgent, spec: AgentSpec): AgentManifest;
+export declare function serializeManifest(manifest: AgentManifest): string;
+export declare function writeManifest(agentDir: string, manifest: AgentManifest): string;

package/dist/agent/manifest.js

@@ -0,0 +1,40 @@
+// The frozen, fully-resolved agent definition. Writing meta/manifest.lock.json
+// makes a decomposed folder as reproducible as pinning a single SKILL.md by
+// commit SHA: anyone can see exactly which knob values (and from which files)
+// produced a run. Deterministic by construction — no timestamps, keys sorted.
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { sha256, stableStringify, toPosix } from "./util.js";
+import { RESOLVER_VERSION, RUNNER_VERSION, MANIFEST_SCHEMA } from "./version.js";
+export function buildManifest(resolved, spec) {
+    // configHash binds the RESOLVED spec to the resolver + schema version, so a
+    // run reproduces only against the same compile (not just the same files).
+    const configHash = sha256(stableStringify({
+        resolvedSpec: spec,
+        resolverVersion: RESOLVER_VERSION,
+        schema: MANIFEST_SCHEMA,
+    }));
+    return {
+        schema: MANIFEST_SCHEMA,
+        spec: spec.spec || "coinrithm.agent.v1",
+        resolverVersion: RESOLVER_VERSION,
+        runnerVersion: RUNNER_VERSION,
+        resolvedConfig: resolved.rawFrontmatter,
+        resolvedSpec: spec,
+        provenance: resolved.provenance,
+        contentHashes: resolved.contentHashes,
+        configHash,
+    };
+}
+// Serialize deterministically (sorted keys, no timestamps) so two compiles of
+// the same inputs on Windows and Linux are byte-identical.
+export function serializeManifest(manifest) {
+    return stableStringify(manifest) + "\n";
+}
+export function writeManifest(agentDir, manifest) {
+    const metaDir = join(agentDir, "meta");
+    mkdirSync(metaDir, { recursive: true });
+    const out = join(metaDir, "manifest.lock.json");
+    writeFileSync(out, serializeManifest(manifest), "utf8");
+    return toPosix(out);
+}

package/dist/agent/mergeRules.d.ts

@@ -0,0 +1,11 @@
+import { ResolveIssue } from "./types.js";
+export type CapDirection = "lower" | "higher" | "true";
+export declare const RISK_CAPS: Record<string, CapDirection>;
+export declare const LIMIT_CAPS: Record<string, CapDirection>;
+export declare function isAtLeastAsRestrictive(dir: CapDirection, candidate: unknown, base: unknown): boolean;
+export declare function mostRestrictive(dir: CapDirection, a: unknown, b: unknown): unknown;
+export interface CapMergeResult {
+    merged: Record<string, unknown>;
+    issues: ResolveIssue[];
+}
+export declare function mergeCapPatch(base: Record<string, unknown>, patch: Record<string, unknown>, caps: Record<string, CapDirection>, sourceLabel: string): CapMergeResult;

package/dist/agent/mergeRules.js

@@ -0,0 +1,82 @@
+// Deterministic merge rules for the agent resolver.
+//
+// Codex audit, adopted: HARD CAPS merge by "most-restrictive-wins", NOT
+// last-writer-wins. A skill/tactic module may only TIGHTEN a cap; any attempt
+// to WIDEN one is rejected (fail-closed), never silently ignored. This makes a
+// decomposed agent strictly safer than its inline form can be — a part-file or
+// a tactic can never loosen a limit, regardless of file/merge order.
+//
+// Normal (non-cap) config uses simple precedence (inline > $ref > defaults),
+// handled in the resolver; this module owns only the cap arithmetic.
+// risk.* hard caps a tactic module may tighten.
+export const RISK_CAPS = {
+    maxLeverage: "lower",
+    perTradeMarginMusd: "lower",
+    maxConcurrentPositions: "lower",
+    requireStopLoss: "true",
+};
+// limits.* throughput/spend caps a tactic module may tighten.
+export const LIMIT_CAPS = {
+    maxTradesPerDay: "lower",
+    maxWritesPerCycle: "lower",
+    maxDailyLossMusd: "lower",
+    maxOpenMarginMusd: "lower",
+};
+// Is `candidate` at least as restrictive as `base` (i.e. a legal tightening)?
+export function isAtLeastAsRestrictive(dir, candidate, base) {
+    if (dir === "true") {
+        // true is tighter than false. candidate must not be LESS strict than base.
+        // legal: base=false→candidate any; base=true→candidate must be true.
+        return base === true ? candidate === true : true;
+    }
+    if (typeof candidate !== "number" || typeof base !== "number") {
+        // a non-numeric cap candidate where a number is expected is not a legal
+        // tightening (caller will surface a type issue separately).
+        return false;
+    }
+    return dir === "lower" ? candidate <= base : candidate >= base;
+}
+// The more-restrictive of two values for a cap field.
+export function mostRestrictive(dir, a, b) {
+    if (dir === "true")
+        return a === true || b === true ? true : false;
+    if (typeof a !== "number")
+        return b;
+    if (typeof b !== "number")
+        return a;
+    return dir === "lower" ? Math.min(a, b) : Math.max(a, b);
+}
+// Merge a tactic-module cap patch onto a base cap block under tighten-only +
+// most-restrictive-wins. `caps` is the field→direction map (RISK_CAPS/LIMIT_CAPS).
+// A patch key that is NOT a known cap, or that WIDENS a cap, is an issue.
+export function mergeCapPatch(base, patch, caps, sourceLabel) {
+    const merged = { ...base };
+    const issues = [];
+    for (const [key, value] of Object.entries(patch)) {
+        const dir = caps[key];
+        if (!dir) {
+            issues.push({
+                code: "skill_patch_unknown_cap",
+                path: sourceLabel,
+                message: `tactic "${sourceLabel}" may only tighten known caps (${Object.keys(caps).join(", ")}); got "${key}"`,
+            });
+            continue;
+        }
+        if (!(key in base) || base[key] === undefined) {
+            // No base to tighten against — accept the value as-is (it can't widen
+            // something that wasn't set; the top-level/defaults still bound it).
+            merged[key] = value;
+            continue;
+        }
+        if (!isAtLeastAsRestrictive(dir, value, base[key])) {
+            issues.push({
+                code: "skill_patch_widens_cap",
+                path: sourceLabel,
+                message: `tactic "${sourceLabel}" tries to WIDEN ${key} (${JSON.stringify(base[key])} → ${JSON.stringify(value)}); a tactic may only tighten`,
+            });
+            continue;
+        }
+        merged[key] = mostRestrictive(dir, base[key], value);
+    }
+    return { merged, issues };
+}

package/dist/agent/observe.d.ts

@@ -0,0 +1,7 @@
+import { CoinRithmClient } from "./client.js";
+import { AgentSpec, RunState, Observation, AgentTrace } from "./types.js";
+export interface ObserveOutput {
+    observation: Observation;
+    skip?: string;
+}
+export declare function observe(client: CoinRithmClient, spec: AgentSpec, state: RunState, trace?: AgentTrace): Promise<ObserveOutput>;

package/dist/agent/observe.js

@@ -0,0 +1,244 @@
+// Observe phase: read CoinRithm state into one Observation. Sync-polls /trades
+// before any write (polledBeforeWrite=true only after that succeeds). If a
+// required read fails, or no watchlist symbol resolves, the cycle SKIPS writes.
+import { asObj, asArr, asNum, asStr } from "./extract.js";
+import { computeIndicators } from "./indicators.js";
+// Candle granularity feeding the indicators: the 1D range = 5-minute candles
+// (~5-min fresh, ~288 bars — ample for EMA50/RSI14/Bollinger20), which suits the
+// short cadence the hosted house agents run on. Probe-verified 2026-06-17.
+const INDICATOR_RANGE = "1D";
+// Fetch candles for one coin and reduce them to a compact indicator bundle.
+// Tolerant by design: any failure (HTTP error, malformed/sparse candles) returns
+// null so the cycle proceeds with price-only context rather than skipping.
+async function fetchIndicators(client, coinId, trace) {
+    const cr = await client.candles(coinId, INDICATOR_RANGE, trace);
+    if (!cr.ok)
+        return null;
+    // Endpoint shape: { candles: [{ t, o, h, l, c, v }] } ascending (oldest first).
+    const candles = [];
+    for (const raw of asArr(asObj(cr.data).candles)) {
+        const c = asObj(raw);
+        const open = asNum(c.o);
+        const high = asNum(c.h);
+        const low = asNum(c.l);
+        const close = asNum(c.c);
+        if (open == null || high == null || low == null || close == null)
+            continue;
+        candles.push({ open, high, low, close, volume: asNum(c.v) ?? undefined });
+    }
+    return computeIndicators(candles);
+}
+function freshnessOf(block) {
+    const fr = asObj(block.freshness);
+    const status = asStr(fr.status);
+    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
+}
+function emptyObservation(state, scopes = []) {
+    return {
+        asOf: state.cursor ?? new Date().toISOString(),
+        scopes,
+        cashAvailableMusd: null,
+        equityMusd: null,
+        openPositions: [],
+        openOrders: [],
+        pmPositions: [],
+        pmMarkets: [],
+        watch: [],
+        syncCursor: state.cursor,
+        newClosedTrades: [],
+        polledBeforeWrite: false,
+    };
+}
+export async function observe(client, spec, state, trace) {
+    const meR = await client.me(trace);
+    if (!meR.ok)
+        return {
+            observation: emptyObservation(state),
+            skip: `me failed (HTTP ${meR.status})`,
+        };
+    const scopes = asArr(asObj(meR.data).scopes).filter((s) => typeof s === "string");
+    const [portR, walletR, posR] = await Promise.all([
+        client.portfolio(trace),
+        client.wallet(undefined, trace),
+        client.futuresPositions(undefined, trace),
+    ]);
+    if (!portR.ok || !walletR.ok || !posR.ok) {
+        return {
+            observation: emptyObservation(state, scopes),
+            skip: "required reads failed (portfolio/wallet/positions)",
+        };
+    }
+    const usdt = asObj(asObj(walletR.data).usdt);
+    const equity = asObj(asObj(portR.data).equity);
+    const cashAvailableMusd = asNum(usdt.available) ?? asNum(equity.availableUsd) ?? null;
+    const equityMusd = asNum(equity.totalUsd) ?? asNum(asObj(portR.data).equityUsd) ?? null;
+    const openPositions = asArr(asObj(posR.data).positions)
+        .map(asObj)
+        .filter((p) => (asStr(p.status) ?? "open") === "open")
+        .map((p) => ({
+        venue: "futures",
+        id: Number(asNum(p.id) ?? p.id),
+        coinId: asStr(p.coinId),
+        symbol: asStr(p.symbol),
+        side: asStr(p.side),
+        status: asStr(p.status) ?? "open",
+        marginMusd: asNum(p.marginMusd),
+        unrealizedPnlMusd: asNum(p.unrealizedPnlMusd),
+    }));
+    // Sync poll: /trades since the persisted cursor.
+    const tradesR = await client.trades({
+        venue: "futures",
+        updatedSince: state.cursor ?? undefined,
+        limit: state.cursor ? undefined : 1,
+    }, trace);
+    let polledBeforeWrite = false;
+    let newClosedTrades = [];
+    let syncCursor = state.cursor;
+    if (tradesR.ok) {
+        polledBeforeWrite = true;
+        const td = asObj(tradesR.data);
+        syncCursor = asStr(td.asOf) ?? state.cursor;
+        newClosedTrades = asArr(td.trades)
+            .map(asObj)
+            .filter((t) => !state.seen.includes(`${asStr(t.venue) ?? "futures"}:${asNum(t.id) ?? t.id}`));
+    }
+    // Watchlist market context.
+    const watch = [];
+    let resolvedAny = false;
+    const wantIndicators = spec.capabilities.includes("indicators");
+    for (const symbol of spec.risk.watchlist) {
+        const rs = await client.resolve(symbol, trace);
+        const match = asObj(asObj(rs.data).match);
+        const coinId = rs.ok && match.coinId != null ? String(match.coinId) : null;
+        if (!coinId) {
+            watch.push({ symbol, coinId: null });
+            continue;
+        }
+        resolvedAny = true;
+        const mk = await client.market(coinId, trace);
+        const m = asObj(mk.data);
+        const price = asObj(m.price);
+        const entry = {
+            symbol,
+            coinId,
+            name: asStr(match.name),
+            priceUsd: asNum(price.usd),
+            change1h: asNum(price.change1h),
+            change24h: asNum(price.change24h),
+            change7d: asNum(price.change7d),
+            // Freshness lives under the response's `observation` block.
+            freshness: freshnessOf(asObj(m.observation)),
+        };
+        // `indicators` capability: enrich the observation with computed TA so the
+        // model reasons over structure (trend/momentum/volatility/breakout) instead
+        // of price + %change alone. Backed by the candles endpoint's shared cache.
+        if (wantIndicators) {
+            const ind = await fetchIndicators(client, coinId, trace);
+            if (ind)
+                entry.indicators = ind;
+        }
+        watch.push(entry);
+    }
+    // Spot resting orders (for cancel + affordability) — only if spot is enabled.
+    const wantSpot = spec.venues.includes("spot");
+    const wantPm = spec.venues.includes("pm");
+    let openOrders = [];
+    if (wantSpot) {
+        const ordR = await client.openOrders(undefined, trace);
+        if (ordR.ok) {
+            const od = asObj(ordR.data);
+            openOrders = asArr(od.orders ?? od.openOrders)
+                .map(asObj)
+                .filter((o) => (asStr(o.status) ?? "open") === "open")
+                .map((o) => ({
+                id: Number(asNum(o.id) ?? o.id),
+                coinId: asStr(o.coinId),
+                symbol: asStr(o.symbol),
+                side: asStr(o.side),
+                orderType: asStr(o.orderType),
+                quantity: asNum(o.quantity),
+                status: asStr(o.status) ?? "open",
+            }));
+        }
+    }
+    // PM open positions + discovered quote-ready candidates — only if pm enabled.
+    let pmPositions = [];
+    let pmMarkets = [];
+    if (wantPm) {
+        const [pmPosR, pmDiscR] = await Promise.all([
+            client.pmPositions(undefined, trace),
+            client.discoverPmMarkets({ limit: 8 }, trace),
+        ]);
+        if (pmPosR.ok) {
+            pmPositions = asArr(asObj(pmPosR.data).positions)
+                .map(asObj)
+                .filter((p) => (asStr(p.status) ?? "open") === "open")
+                .map((p) => ({
+                id: Number(asNum(p.id) ?? p.id),
+                source: asStr(p.source),
+                slug: asStr(p.slug),
+                outcomeExternalMarketId: asStr(p.outcomeExternalMarketId),
+                stakeMusd: asNum(p.stakeMusd),
+                status: asStr(p.status) ?? "open",
+            }));
+        }
+        if (pmDiscR.ok) {
+            const dd = asObj(pmDiscR.data);
+            // Real /api/agent/pm/discover payload: { data: [event], pagination, meta }.
+            // Each EVENT carries source/slug/title/freshness at the top level and the
+            // quoteable id NESTED at outcomes[].externalMarketId — so expand one
+            // PmMarket per quoteable outcome. (Tolerant `markets`/`results` and flat
+            // `outcomeExternalMarketId` fallbacks kept for older/mocked shapes.)
+            pmMarkets = asArr(dd.data ?? dd.markets ?? dd.results)
+                .map(asObj)
+                .flatMap((ev) => {
+                const source = (asStr(ev.source) ?? "").toLowerCase();
+                const slug = (asStr(ev.slug) ?? "").toLowerCase();
+                const title = asStr(ev.title) ?? asStr(ev.question);
+                const freshness = freshnessOf(ev); // freshness is event-level
+                const outcomes = asArr(ev.outcomes).map(asObj);
+                // A market with no outcomes array still round-trips a flat fallback row.
+                const rows = outcomes.length > 0 ? outcomes : [ev];
+                return rows.map((o) => ({
+                    source,
+                    slug,
+                    outcomeExternalMarketId: asStr(o.externalMarketId) ??
+                        asStr(o.outcomeExternalMarketId) ??
+                        "",
+                    title,
+                    freshness,
+                }));
+            })
+                .filter((m) => m.source && m.slug && m.outcomeExternalMarketId);
+        }
+    }
+    const observation = {
+        asOf: syncCursor ?? new Date().toISOString(),
+        scopes,
+        cashAvailableMusd,
+        equityMusd,
+        openPositions,
+        openOrders,
+        pmPositions,
+        pmMarkets,
+        watch,
+        syncCursor,
+        newClosedTrades,
+        polledBeforeWrite,
+    };
+    // Skip only when there is NOTHING actionable: no coin resolved (futures/spot)
+    // AND no PM candidate (pm). A pm-only agent proceeds on its discovered markets.
+    if (!resolvedAny && pmMarkets.length === 0) {
+        return {
+            observation,
+            skip: "no watchlist coin resolved and no PM markets available",
+        };
+    }
+    if (spec.sync.requirePollBeforeWrite && !polledBeforeWrite) {
+        return {
+            observation,
+            skip: "poll-before-write required but /trades poll failed",
+        };
+    }
+    return { observation };
+}

package/dist/agent/prompt.d.ts

@@ -0,0 +1,3 @@
+import { AgentSpec, Observation } from "./types.js";
+export declare function buildSystemPrompt(spec: AgentSpec, mergedProse: string): string;
+export declare function buildUserPrompt(obs: Observation): string;

package/dist/agent/prompt.js

@@ -0,0 +1,76 @@
+// Build the system + user prompts for one decide step. The system prompt is the
+// static character (cached prefix); the user prompt is the fresh observation.
+// The model only PROPOSES — the runner re-checks every action against the caps,
+// so the prompt states the caps but never relies on the model to honor them.
+export function buildSystemPrompt(spec, mergedProse) {
+    const r = spec.risk;
+    const v = spec.venues;
+    const actions = [];
+    if (v.includes("futures")) {
+        actions.push('{"type":"futures_open","symbol","side":"long"|"short","leverage","marginMusd","stopLossPrice","takeProfitPrice","confidence":0..1}', '{"type":"futures_close","positionId","fraction"}', '{"type":"futures_set_sltp","positionId","stopLossPrice","takeProfitPrice"}');
+    }
+    if (v.includes("spot")) {
+        actions.push('{"type":"spot_order","symbol","side":"buy"|"sell","orderType":"market"|"limit"|"stop","quantity","limitPrice","stopPrice","confidence":0..1}', '{"type":"spot_cancel","orderId"}');
+    }
+    if (v.includes("pm")) {
+        actions.push('{"type":"pm_open","source","slug","outcomeExternalMarketId","stakeMusd","confidence":0..1}  (ONLY a market from observation.pmMarkets; stakeMusd >= 10)');
+    }
+    return [
+        "You operate a CoinRithm PAPER-TRADING agent (simulated 50,000 mUSD; not real money, not financial advice).",
+        "You only PROPOSE actions as structured JSON. A separate runner re-validates every action against hard caps and executes it; you cannot bypass a cap.",
+        "",
+        "## Your strategy (your borders)",
+        mergedProse.trim() || "(no strategy prose provided)",
+        "",
+        "## Hard caps the runner enforces (do not exceed; proposing over a cap wastes the cycle)",
+        `- venues you may act in: ${v.join(", ")}`,
+        `- perTradeMarginMusd ${r.perTradeMarginMusd} is the per-trade SIZE cap (futures margin / spot buy notional / PM stake)`,
+        `- futures: maxLeverage ${r.maxLeverage}, maxConcurrentPositions ${r.maxConcurrentPositions}, requireStopLoss ${r.requireStopLoss} (long stop below entry, short stop above)`,
+        `- watchlist (spot + futures use ONLY these): ${r.watchlist.join(", ")}`,
+        ...(r.blocklist && r.blocklist.length > 0
+            ? [
+                `- deny-list (NEVER open these, even if on the watchlist): ${r.blocklist.join(", ")}`,
+            ]
+            : []),
+        "- prediction markets: pick ONLY a market listed in observation.pmMarkets; minimum stake 10 mUSD",
+        `- abstention.minConfidence ${spec.abstention.minConfidence}; a skipped cycle is correct and cheap`,
+        ...(spec.capabilities.includes("indicators")
+            ? [
+                "",
+                "## Signals — each watch entry may carry `indicators` (computed from 5-minute candles)",
+                "- rsi14: momentum (>70 overbought, <30 oversold); ema20 & ema50: trend; atr14: volatility (size stops off it); bollinger {upper,mid,lower}; recent20 {high,low}: breakout levels.",
+                "- boolean reads: aboveEma20, ema20AboveEma50 (uptrend when both true), brokeRecentHigh (breakout), brokeRecentLow (breakdown).",
+                "- a null field = not enough data; ignore it. These INFORM your decision; they never widen a cap.",
+            ]
+            : []),
+        "",
+        "## Output contract — return ONLY this JSON object, nothing else:",
+        '{"decision":"skip"|"act","confidence":0..1,"reason":"short","actions":[]}',
+        "Each action is one of:",
+        ...actions.map((a) => `- ${a}`),
+        `Set each opening action's "confidence" (0..1) to your honest conviction — the runner REJECTS any open below abstention.minConfidence (${spec.abstention.minConfidence}). The decision-level "confidence" is the fallback when an action omits its own.`,
+        "Prefer skip when the signal is weak or data is stale.",
+    ].join("\n");
+}
+export function buildUserPrompt(obs) {
+    return [
+        "Decide for THIS cycle using only the observation below (data available now — no look-ahead).",
+        "",
+        "```json",
+        JSON.stringify({
+            asOf: obs.asOf,
+            cashAvailableMusd: obs.cashAvailableMusd,
+            equityMusd: obs.equityMusd,
+            openPositions: obs.openPositions,
+            openOrders: obs.openOrders,
+            pmPositions: obs.pmPositions,
+            pmMarkets: obs.pmMarkets,
+            watch: obs.watch,
+            newClosedTrades: obs.newClosedTrades,
+            polledBeforeWrite: obs.polledBeforeWrite,
+        }, null, 2),
+        "```",
+        "",
+        "Return ONLY the JSON decision object.",
+    ].join("\n");
+}

package/dist/agent/providers.d.ts

@@ -0,0 +1,25 @@
+import { AgentSpec } from "./types.js";
+export interface DecideInput {
+    system: string;
+    user: string;
+    maxTokens?: number;
+}
+export type DecideResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
+export interface Provider {
+    label: string;
+    decide(input: DecideInput): Promise<DecideResult>;
+}
+export interface ProviderEnv {
+    ANTHROPIC_API_KEY?: string;
+    OPENAI_API_KEY?: string;
+    GROQ_API_KEY?: string;
+    NVIDIA_API_KEY?: string;
+    MODEL_API_KEY?: string;
+}
+export declare function selectProvider(spec: AgentSpec, env: ProviderEnv, fetchFn?: typeof fetch): Provider;