@coinrithm/mcp-trading 0.2.0 → 0.4.0

package/dist/agent/observe.js

@@ -2,6 +2,32 @@
 // 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);
@@ -14,6 +40,9 @@ function emptyObservation(state, scopes = []) {
         cashAvailableMusd: null,
         equityMusd: null,
         openPositions: [],
+        openOrders: [],
+        pmPositions: [],
+        pmMarkets: [],
         watch: [],
         syncCursor: state.cursor,
         newClosedTrades: [],
@@ -23,7 +52,10 @@ function emptyObservation(state, scopes = []) {
 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})` };
+        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),
@@ -31,7 +63,10 @@ export async function observe(client, spec, state, trace) {
         client.futuresPositions(undefined, trace),
     ]);
     if (!portR.ok || !walletR.ok || !posR.ok) {
-        return { observation: emptyObservation(state, scopes), skip: "required reads failed (portfolio/wallet/positions)" };
+        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);
@@ -51,7 +86,11 @@ export async function observe(client, spec, state, trace) {
         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);
+    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;
@@ -66,6 +105,7 @@ export async function observe(client, spec, state, trace) {
     // 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);
@@ -78,7 +118,7 @@ export async function observe(client, spec, state, trace) {
         const mk = await client.market(coinId, trace);
         const m = asObj(mk.data);
         const price = asObj(m.price);
-        watch.push({
+        const entry = {
             symbol,
             coinId,
             name: asStr(match.name),
@@ -88,7 +128,89 @@ export async function observe(client, spec, state, trace) {
             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(),
@@ -96,15 +218,27 @@ export async function observe(client, spec, state, trace) {
         cashAvailableMusd,
         equityMusd,
         openPositions,
+        openOrders,
+        pmPositions,
+        pmMarkets,
         watch,
         syncCursor,
         newClosedTrades,
         polledBeforeWrite,
     };
-    if (!resolvedAny)
-        return { observation, skip: "no watchlist symbol resolved to a coin" };
+    // 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,
+            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

@@ -4,24 +4,52 @@
 // 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 futures agent (simulated 50,000 mUSD; not real money, not financial advice).",
+        "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: ${spec.venues.join(", ")} (v1 executes FUTURES only)`,
-        `- maxLeverage ${r.maxLeverage}; perTradeMarginMusd ${r.perTradeMarginMusd}; maxConcurrentPositions ${r.maxConcurrentPositions}; requireStopLoss ${r.requireStopLoss}`,
-        `- watchlist (only these): ${r.watchlist.join(", ")}`,
+        `- 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: {"type":"futures_open","symbol","side":"long"|"short","leverage","marginMusd","stopLossPrice","takeProfitPrice"},',
-        '{"type":"futures_close","positionId","fraction"}, {"type":"futures_set_sltp","positionId","stopLossPrice","takeProfitPrice"}.',
-        "Always include a stopLossPrice on a futures_open. Prefer skip when the signal is weak or data is stale.",
+        '{"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) {
@@ -34,6 +62,9 @@ export function buildUserPrompt(obs) {
             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,

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;

package/dist/agent/providers.js

@@ -2,6 +2,9 @@
 // never from an agent file. One call returns one chunk of text that must be a
 // single structured-JSON decision (parsed in decision.ts). No free-form tool
 // execution — the model only proposes; the runner disposes.
+// NVIDIA NIM is OpenAI-compatible; the `nvidia` preset hard-wires the hosted
+// endpoint so an agent only needs `{ provider: nvidia, name: "<model id>" }`.
+const NVIDIA_BASE_URL = "https://integrate.api.nvidia.com/v1";
 function envKey(provider, env) {
     switch (provider) {
         case "anthropic":
@@ -10,6 +13,8 @@ function envKey(provider, env) {
             return env.OPENAI_API_KEY;
         case "groq":
             return env.GROQ_API_KEY;
+        case "nvidia":
+            return env.NVIDIA_API_KEY ?? env.MODEL_API_KEY;
         case "openai-compatible":
             return env.MODEL_API_KEY ?? env.OPENAI_API_KEY;
     }
@@ -20,6 +25,8 @@ function baseUrlFor(provider, configured) {
             return "https://api.openai.com/v1";
         case "groq":
             return "https://api.groq.com/openai/v1";
+        case "nvidia":
+            return NVIDIA_BASE_URL;
         case "openai-compatible":
             return (configured ?? "").replace(/\/+$/, "");
         case "anthropic":
@@ -121,7 +128,9 @@ export function selectProvider(spec, env, fetchFn = fetch) {
             ? "ANTHROPIC_API_KEY"
             : provider === "groq"
                 ? "GROQ_API_KEY"
-                : "OPENAI_API_KEY / MODEL_API_KEY";
+                : provider === "nvidia"
+                    ? "NVIDIA_API_KEY"
+                    : "OPENAI_API_KEY / MODEL_API_KEY";
         throw new Error(`missing model API key: set ${varName} in the environment (never in an agent file)`);
     }
     if (provider === "anthropic")

package/dist/agent/resolve.d.ts

@@ -0,0 +1,11 @@
+import { ResolvedAgent, ResolveIssue } from "./types.js";
+export declare class ResolveError extends Error {
+    issues: ResolveIssue[];
+    constructor(issues: ResolveIssue[]);
+}
+export declare function isSkillProseSource(source: string): boolean;
+export declare function mergeProseParts(parts: Array<{
+    source: string;
+    text: string;
+}>): string;
+export declare function resolveAgent(inputPath: string): ResolvedAgent;

package/dist/agent/resolve.js

@@ -48,6 +48,7 @@ const JOURNAL_MAX_LINES = 200;
 const JOURNAL_MAX_BYTES = 8_000;
 // Optional prose files (markdown the LLM reads), in assembly order.
 const PROSE_FILES = ["character/thesis.md", "character/persona.md"];
+const FUNCTIONALITY_PIN = "functionality/coinrithm.yaml";
 // Enforced cap field names. sizing.yaml is SOFT guidance and must NOT contain
 // any of these (or a user could think a limit binds when it does not).
 const ENFORCED_FIELD_NAMES = new Set([
@@ -58,6 +59,7 @@ const ENFORCED_FIELD_NAMES = new Set([
     "maxConsecutiveModelFailures",
     "onRateLimitPressure",
 ]);
+const SKILL_METADATA_KEYS = new Set(["type", "title", "description", "tags"]);
 // A $ref must be a LOCAL, RELATIVE path inside the agent folder — never a URL,
 // an absolute path, a home/drive path, or a Windows backslash path.
 function refSyntaxIssue(ref) {
@@ -391,6 +393,13 @@ function resolveDirectory(dir) {
             // a skill file may be pure prose (no frontmatter) — treat whole as body.
             body = readFileSync(abs, "utf8");
         }
+        for (const f of scanForSecrets(patch)) {
+            ctx.issues.push({
+                code: "secret_in_frontmatter",
+                path: refPath,
+                message: `${f} (skill frontmatter is committable metadata — remove secrets)`,
+            });
+        }
         includeOrder.push(name);
         skillProse.push({ source: refPath, text: body });
         applySkillPatch(ctx, rawFrontmatter, patch, refPath);
@@ -420,9 +429,24 @@ function resolveDirectory(dir) {
             });
         }
     }
-    const mergedProse = proseParts
-        .map((p) => `<!-- ${p.source} -->\n${p.text.trim()}`)
-        .join("\n\n");
+    // Optional API/tool contract pin. It is locked for reproducibility and stale
+    // warnings, but it is not part of AgentSpec and is never sent to the model.
+    const functionalityPath = join(dir, FUNCTIONALITY_PIN);
+    if (existsSync(functionalityPath)) {
+        const abs = safePath(ctx, FUNCTIONALITY_PIN, "functionality pin");
+        if (abs) {
+            const parsed = parseYamlSafe(ctx, readHashed(ctx, abs), FUNCTIONALITY_PIN);
+            for (const f of scanForSecrets(parsed)) {
+                ctx.issues.push({
+                    code: "secret_in_functionality",
+                    path: FUNCTIONALITY_PIN,
+                    message: `${f} (the functionality pin is committable metadata — remove secrets)`,
+                });
+            }
+            sources.functionality = FUNCTIONALITY_PIN;
+        }
+    }
+    const mergedProse = mergeProseParts(proseParts);
     checkSizing(ctx, rawFrontmatter);
     scanSecrets(ctx, rawFrontmatter, mergedProse);
     if (ctx.issues.length)
@@ -446,6 +470,8 @@ function resolveDirectory(dir) {
 // permitted, tighten-only; anything else is rejected (no permission expansion).
 function applySkillPatch(ctx, rawFrontmatter, patch, sourceLabel) {
     for (const key of Object.keys(patch)) {
+        if (SKILL_METADATA_KEYS.has(key))
+            continue;
         if (key === "risk" || key === "limits") {
             const caps = key === "risk" ? RISK_CAPS : LIMIT_CAPS;
             const base = rawFrontmatter[key] ?? {};
@@ -472,6 +498,17 @@ function applySkillPatch(ctx, rawFrontmatter, patch, sourceLabel) {
     }
 }
 // ── entry point ──────────────────────────────────────────────────────────────
+// Is this prose part a tactic skill? (Used by the skills ablation kill-switch to
+// drop skill bodies from the run-time prompt without touching the resolver.)
+export function isSkillProseSource(source) {
+    return source.startsWith("character/skills/");
+}
+// The canonical prose assembly: each part labelled with its source, joined by a
+// blank line. The resolver uses this for mergedProse; the run path reuses it to
+// re-assemble a skills-ablated prompt deterministically.
+export function mergeProseParts(parts) {
+    return parts.map((p) => `<!-- ${p.source} -->\n${p.text.trim()}`).join("\n\n");
+}
 export function resolveAgent(inputPath) {
     const abs = resolvePath(inputPath);
     if (!existsSync(abs)) {

package/dist/agent/runEvidence.d.ts

@@ -0,0 +1,6 @@
+import { CoinRithmClient } from "./client.js";
+import { AgentSpec, AgentTrace } from "./types.js";
+export declare function makeRunId(spec: AgentSpec): string;
+export declare function makeDecisionId(cycle: number): string;
+export declare function makeTrace(runId: string, decisionId: string, spec: AgentSpec, confidence?: number, rationaleSummary?: string): AgentTrace;
+export declare function exportRunEvidence(client: CoinRithmClient, runId: string): Promise<unknown>;

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[]>;