@coinrithm/mcp-trading 0.7.5 → 0.7.7

package/dist/agent/cli.js

@@ -7,7 +7,7 @@
 import { mkdirSync, writeFileSync, existsSync, statSync, readFileSync, openSync, closeSync, unlinkSync, } from "node:fs";
 import { resolve as resolvePath, dirname, join, basename } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { resolveAgent, ResolveError, mergeProseParts, isSkillProseSource, } from "./resolve.js";
+import { resolveAgent, ResolveError, mergeProseParts, isSkillProseSource, hostedProseBudget, HOSTED_PROSE_MAX_CHARS, } from "./resolve.js";
 import { buildSpec, loadAgent } from "./skill.js";
 import { validateSkill } from "./skillValidator.js";
 import { strictLint } from "./strictLint.js";
@@ -101,6 +101,27 @@ export function cmdValidate(path, mode = "self-host") {
     const spec = buildSpec(raw);
     const lint = [...strictLint(raw), ...checkCapabilityDrift(resolved, spec)];
     const v = validateSkill({ spec, body: resolved.mergedProse, raw }, mode);
+    // Hosted-only: the managed deploy/edit API caps the merged strategy prose at
+    // HOSTED_PROSE_MAX_CHARS and REVERTS the save when it is exceeded, so a
+    // bundle that resolves and lints perfectly can still be undeployable through
+    // the Studio. Measured 2026-08-19 after a user hit the wall: 4 of 9 example
+    // bundles were over (contrarian-carl 8,159, mia 8,175, olivia 8,587,
+    // pia-pump-fader 11,787) while the corpus README claimed they all pass
+    // `validate --hosted`. Checking it here is what makes that claim true and
+    // stops the corpus drifting back over the wall.
+    if (mode === "hosted") {
+        const budget = hostedProseBudget(resolved.mergedProse);
+        if (!budget.fits) {
+            lint.push({
+                code: "hosted_prose_too_long",
+                path: "character/*.md",
+                message: `merged strategy prose is ${budget.used} chars, ${budget.over} over the hosted ` +
+                    `limit of ${HOSTED_PROSE_MAX_CHARS} — the managed deploy would reject this and ` +
+                    `revert to the template. Self-host has no such cap. Note the count includes a ` +
+                    `"<!-- path -->" header per prose file, not just the bodies.`,
+            });
+        }
+    }
     const lintFatal = mode === "hosted";
     const lines = [];
     for (const i of lint) {

package/dist/agent/client.d.ts

@@ -21,6 +21,7 @@ export interface ClientConfig {
     fetchFn?: typeof fetch;
     sleepFn?: (ms: number) => Promise<void>;
     maxRetries?: number;
+    extraHeaders?: Record<string, string>;
 }
 export declare class CoinRithmClient {
     private readonly apiKey;
@@ -28,6 +29,7 @@ export declare class CoinRithmClient {
     private readonly fetchFn;
     private readonly sleepFn;
     private readonly maxRetries;
+    private readonly extraHeaders?;
     rateLimitHits: number;
     constructor(cfg: ClientConfig);
     private request;
@@ -37,6 +39,7 @@ export declare class CoinRithmClient {
         coinId?: string;
     }, trace?: AgentTrace): Promise<ApiResult>;
     resolve(q: string, trace?: AgentTrace): Promise<ApiResult>;
+    cryptoMovers(direction: "gainers" | "losers", limit: number, trace?: AgentTrace): Promise<ApiResult>;
     market(coinId: string, trace?: AgentTrace): Promise<ApiResult>;
     candles(coinId: string, range: string, trace?: AgentTrace): Promise<ApiResult>;
     trades(query?: {

package/dist/agent/client.js

@@ -30,6 +30,7 @@ export class CoinRithmClient {
     fetchFn;
     sleepFn;
     maxRetries;
+    extraHeaders;
     // Every 429 seen this session (read or write, retried or not) — feeds the
     // rate-limit-pressure kill-switch, which a write-only counter would miss.
     rateLimitHits = 0;
@@ -39,6 +40,7 @@ export class CoinRithmClient {
         this.fetchFn = cfg.fetchFn ?? fetch;
         this.sleepFn = cfg.sleepFn ?? realSleep;
         this.maxRetries = cfg.maxRetries ?? 3;
+        this.extraHeaders = cfg.extraHeaders;
     }
     async request(method, path, opts = {}) {
         const url = new URL(this.baseUrl + path);
@@ -48,7 +50,9 @@ export class CoinRithmClient {
                     url.searchParams.set(k, String(v));
             }
         }
+        // extraHeaders first: auth, accept and trace can never be clobbered by it.
         const headers = {
+            ...this.extraHeaders,
             Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
             ...traceHeaders(opts.trace),
@@ -116,6 +120,13 @@ export class CoinRithmClient {
     resolve(q, trace) {
         return this.request("GET", "/api/agent/resolve", { query: { q }, trace });
     }
+    // Keyless public universe scan (top 24h movers). The Bearer header rides
+    // along harmlessly — the /api/coins routes are public and ignore it.
+    cryptoMovers(direction, limit, trace) {
+        return this.request("GET", direction === "losers"
+            ? "/api/coins/top-losers"
+            : "/api/coins/top-gainers", { query: { limit }, trace });
+    }
     market(coinId, trace) {
         return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { trace });
     }

package/dist/agent/decision.d.ts

@@ -53,16 +53,22 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     positionId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
     stopLossPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
     takeProfitPrice: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
+    rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     type: "futures_set_sltp";
     stopLossPrice?: any;
     takeProfitPrice?: any;
     positionId?: any;
+    confidence?: any;
+    rationaleSummary?: string | undefined;
 }, {
     type: "futures_set_sltp";
     stopLossPrice?: unknown;
     takeProfitPrice?: unknown;
     positionId?: unknown;
+    confidence?: unknown;
+    rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_order">;
     symbol: z.ZodString;
@@ -96,11 +102,17 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
 }>, z.ZodObject<{
     type: z.ZodLiteral<"spot_cancel">;
     orderId: z.ZodEffects<z.ZodTypeAny, any, unknown>;
+    confidence: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodTypeAny, any, unknown>>>, any, unknown>;
+    rationaleSummary: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     type: "spot_cancel";
+    confidence?: any;
+    rationaleSummary?: string | undefined;
     orderId?: any;
 }, {
     type: "spot_cancel";
+    confidence?: unknown;
+    rationaleSummary?: string | undefined;
     orderId?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"pm_open">;

package/dist/agent/decision.js

@@ -59,6 +59,13 @@ const futuresSetSltp = z
     positionId: num(z.number()),
     stopLossPrice: num(z.number()).nullable().optional(),
     takeProfitPrice: num(z.number()).nullable().optional(),
+    // Accepted-and-unused: the output contract asks for per-action confidence,
+    // so models copy it onto EVERY action. The two schemas that lacked it were
+    // fail-closing whole decisions under .strict() (~180-200 discarded
+    // fleet-wide per day, live-measured 2026-08-19). Same tolerance the four
+    // trade actions already have.
+    confidence,
+    rationaleSummary: z.string().optional(),
 })
     .strict();
 const spotOrder = z
@@ -78,6 +85,9 @@ const spotCancel = z
     .object({
     type: z.literal("spot_cancel"),
     orderId: num(z.number()),
+    // Same accepted-and-unused tolerance as futures_set_sltp above.
+    confidence,
+    rationaleSummary: z.string().optional(),
 })
     .strict();
 // pm_open accepts EITHER a short ref (pm1…pmN, what the prompt now asks for) OR

package/dist/agent/decisionProbe.d.ts

@@ -0,0 +1,17 @@
+import { ProviderName } from "./types.js";
+export interface ProbeRoute {
+    provider: ProviderName;
+    model: string;
+    baseUrl?: string | null;
+    key: string;
+}
+export type ProbeDecisionResult = {
+    ok: true;
+} | {
+    ok: false;
+    stage: "http" | "empty" | "parse";
+    error: string;
+    status?: number;
+    retryAfterMs?: number;
+};
+export declare function probeDecisionContract(route: ProbeRoute, fetchFn?: typeof fetch): Promise<ProbeDecisionResult>;

package/dist/agent/decisionProbe.js

@@ -0,0 +1,70 @@
+// Representative decision probe (reliability slice A, contract frozen on
+// Telegram 2026-08-26). An HTTP-200 chat ping is NOT proof a route can run an
+// agent: the 62f3a12 incident had 200s all round while every cycle failed with
+// "Unexpected token W" (think-chain in the JSON slot), and Codex's gpt-5-nano
+// probe at 256 completion tokens returned EMPTY content with a length finish
+// because reasoning consumed the budget. A route is eligible only when a real
+// call comes back parseable through the REAL decision parser with a non-empty
+// decision — using the exact request shape a cycle would send
+// (providerForRoute -> the same provider classes as the runner).
+//
+// Uses: boot eligibility of fallback-chain targets (slice B), circuit
+// half-open reopens, any future model migration (D18: probe before adopt).
+// The key is used for the one call and never logged; provider error text is
+// sanitized before it can reach any log or ledger row.
+import { providerForRoute } from "./providers.js";
+import { chatShapeFor } from "./providerCapabilities.js";
+import { parseDecision } from "./decision.js";
+// A canned mini-observation whose ONLY correct answer is a tiny skip decision.
+// Small enough to cost nothing, real enough to exercise the full JSON contract.
+const PROBE_SYSTEM = [
+    "You are a trading agent contract probe.",
+    'Reply with EXACTLY one JSON object: {"decision":"skip","reason":"contract probe"}.',
+    "No prose, no code fences, no additional keys.",
+].join(" ");
+const PROBE_USER = "Observation: BTC 24h change 0.0%. Confirm the decision contract.";
+const PROBE_TIMEOUT_MS = 30_000;
+/** Strip the key (and bearer echoes) out of any text a probe might surface. */
+function sanitize(text, key) {
+    let out = (text ?? "").slice(0, 400);
+    if (key)
+        out = out.split(key).join("***");
+    out = out.replace(/Bearer\s+[A-Za-z0-9._-]{8,}/g, "Bearer ***");
+    return out.slice(0, 200);
+}
+export async function probeDecisionContract(route, fetchFn = fetch) {
+    const shape = chatShapeFor(route.provider, route.model, route.baseUrl ?? undefined);
+    const provider = providerForRoute(route, route.key, fetchFn);
+    const res = await provider.decide({
+        system: PROBE_SYSTEM,
+        user: PROBE_USER,
+        // Reasoning models spend hidden tokens first — grant at least the family
+        // floor (1024) or the empty-with-length-finish false negative comes back.
+        maxTokens: Math.max(1024, shape.minProbeCompletionTokens),
+        timeoutMs: PROBE_TIMEOUT_MS,
+    });
+    if (!res.ok) {
+        const error = sanitize(res.error, route.key);
+        // Provider classes report empty 2xx content as "... returned empty content".
+        const stage = /returned empty content/i.test(res.error) ? "empty" : "http";
+        return {
+            ok: false,
+            stage,
+            error,
+            status: res.status,
+            retryAfterMs: res.retryAfterMs,
+        };
+    }
+    if (!res.text.trim()) {
+        return { ok: false, stage: "empty", error: "empty completion" };
+    }
+    const parsed = parseDecision(res.text);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            stage: "parse",
+            error: sanitize(parsed.error, route.key),
+        };
+    }
+    return { ok: true };
+}

package/dist/agent/decisionValidator.js

@@ -36,6 +36,29 @@ export function validateAction(action, ctx) {
             }
         }
     }
+    // Direction constraint (2026-08-24): a strategy's side restriction is a HARD
+    // cap, not prose-obedience. Live incident: a short-only fade agent opened
+    // two momentum LONGS when the flagged-setups act-pressure outweighed its
+    // prose. Closes/SL-TP/cancels are never direction-gated — reducing or
+    // protecting an existing position is not a directional bet.
+    const direction = spec.risk.direction;
+    if (direction) {
+        if (action.type === "futures_open") {
+            if (direction === "short_only" && action.side !== "short") {
+                return fail("direction_constraint", `direction ${direction}: futures_open side must be "short", got "${action.side}"`);
+            }
+            if (direction === "long_only" && action.side !== "long") {
+                return fail("direction_constraint", `direction ${direction}: futures_open side must be "long", got "${action.side}"`);
+            }
+        }
+        // Spot buys are long exposure; a short_only agent must not accumulate
+        // them. Spot sells reduce a holding and stay allowed.
+        if (action.type === "spot_order" &&
+            direction === "short_only" &&
+            action.side === "buy") {
+            return fail("direction_constraint", `direction ${direction}: spot buys are long exposure`);
+        }
+    }
     if (action.type === "futures_open") {
         // Daily realized-loss stop: once today's loss hits the cap, open no new risk.
         if (spec.limits.maxDailyLossMusd > 0 &&

package/dist/agent/engine.d.ts

@@ -1,5 +1,8 @@
 export { runCycle, type RunnerDeps } from "./runner.js";
-export { selectProvider, type ProviderEnv, type Provider, } from "./providers.js";
+export { selectProvider, providerForRoute, type ProviderEnv, type Provider, type DecideInput, type DecideResult, type DecideRouteAttempt, type DecideRouteMeta, } from "./providers.js";
+export { parseDecision } from "./decision.js";
+export { chatShapeFor, buildChatBody, type ChatShape, } from "./providerCapabilities.js";
+export { probeDecisionContract, type ProbeRoute, type ProbeDecisionResult, } from "./decisionProbe.js";
 export { CoinRithmClient } from "./client.js";
 export { loadAgent, buildSpec, type LoadedAgent } from "./skill.js";
 export { resolveAgent } from "./resolve.js";

package/dist/agent/engine.js

@@ -6,7 +6,13 @@
 // This barrel is the ONE import a host scheduler needs; it re-exports only the
 // stable engine pieces, never the CLI.
 export { runCycle } from "./runner.js";
-export { selectProvider, } from "./providers.js";
+export { selectProvider, providerForRoute, } from "./providers.js";
+export { parseDecision } from "./decision.js";
+// Reliability slice A: the declarative request-capability table and the
+// representative decision probe (route eligibility = a REAL parsed decision,
+// never a bare HTTP 200 — the 62f3a12 lesson).
+export { chatShapeFor, buildChatBody, } from "./providerCapabilities.js";
+export { probeDecisionContract, } from "./decisionProbe.js";
 export { CoinRithmClient } from "./client.js";
 export { loadAgent, buildSpec } from "./skill.js";
 export { resolveAgent } from "./resolve.js";

package/dist/agent/observe.js

@@ -8,6 +8,29 @@ import { scanSetups } from "./setups.js";
 // (~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";
+// `universe_scan` bounds: how many top movers to pull, and how many of those
+// to fully resolve into tradable watch entries (each resolved row costs a
+// resolve + market [+ candles] call).
+//
+// RESOLVE_TOP 3 -> 6 on 2026-08-21. Only a resolved row carries indicators, and
+// therefore a `setups` flag; the unresolved remainder is bare symbol + 24h
+// change + price. At 3, a discovery-driven strategy could reason properly about
+// exactly three coins per cycle out of fifteen surfaced.
+//
+// That bit a real user case. A pump-fade agent identifies a candidate from a
+// `stretched`/`fade-short` setup (RSI14 >= 68) and then waits for exhaustion,
+// which by definition means RSI is NO LONGER extreme. Nothing persists between
+// cycles, so the candidate has to still be a resolved row at the moment the
+// exhaustion evidence appears. Discovery is gainers-ranked, so a retracing coin
+// slides down the list — at 3 it fell out almost immediately and went blind
+// exactly when the strategy needed to look at it.
+//
+// 6 roughly doubles how far a coin can slide before losing its indicators. Cost
+// is 3 extra market+candles calls per cycle against CoinRithm's own API (never
+// the model quota) and ~3 more watch entries in the prompt, and only for agents
+// that declare universe_scan.
+const UNIVERSE_SCAN_LIMIT = 15;
+const UNIVERSE_RESOLVE_TOP = 6;
 // Watchlist symbols -> the coin NAMES prediction-market titles use, so an agent
 // discovers PM markets about the coins it actually has a price view on.
 const PM_COIN_NAMES = {
@@ -42,7 +65,16 @@ export function isCalibrationChurnMarket(market) {
 // 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);
+    // The try honors the documented tolerance for SYNCHRONOUS throws too (an
+    // unexpected client error must degrade to price-only context, never kill
+    // the cycle).
+    let cr;
+    try {
+        cr = await client.candles(coinId, INDICATOR_RANGE, trace);
+    }
+    catch {
+        return null;
+    }
     if (!cr.ok)
         return null;
     // Endpoint shape: { candles: [{ t, o, h, l, c, v }] } ascending (oldest first).
@@ -272,6 +304,78 @@ export async function observe(client, spec, state, trace) {
         }
         watch.push(entry);
     }
+    // `universe_scan` capability (2026-08-18, direct user request): discover the
+    // top 24h movers across the whole tracked universe, resolve the strongest
+    // few into FULL watch entries (marked discovered) and pass the remainder as
+    // compact context. Bounds: one movers call + up to
+    // UNIVERSE_RESOLVE_TOP resolve/market(+candles) calls per cycle — the same
+    // per-symbol cost as ~3 extra watchlist rows, all against CoinRithm's own
+    // API (never the model quota). Failures degrade to "no universe section",
+    // never a skipped cycle. Watchlist + blocklist symbols are excluded up
+    // front so a discovered row can never duplicate or bypass the deny-list.
+    let universeMovers;
+    if (spec.capabilities.includes("universe_scan")) {
+        const mv = await client.cryptoMovers("gainers", UNIVERSE_SCAN_LIMIT, trace);
+        if (mv.ok && Array.isArray(mv.data)) {
+            const excluded = new Set([...spec.risk.watchlist, ...(spec.risk.blocklist ?? [])].map((s) => s.toUpperCase()));
+            const rows = mv.data
+                .map(asObj)
+                .map((r) => ({
+                symbol: (asStr(r.symbol) ?? "").toUpperCase(),
+                name: asStr(r.name),
+                change24hPct: asNum(r.change24h),
+                priceUsd: asNum(r.currentPrice),
+                // The movers row already carries the ucid, which IS the coinId every
+                // downstream call takes. Kept so the resolve round-trip below can be
+                // skipped — see the comment there.
+                coinId: asStr(r.ucid),
+            }))
+                .filter((r) => r.symbol && !excluded.has(r.symbol));
+            const resolveTop = rows.slice(0, UNIVERSE_RESOLVE_TOP);
+            for (const row of resolveTop) {
+                // Prefer the ucid the movers feed already gave us. Resolving the
+                // SYMBOL instead was both a wasted call per discovered mover and a
+                // correctness hazard: symbols collide across listings, so the resolver
+                // could hand back a different coin than the one that actually moved,
+                // and the agent would analyze (and trade) that other coin.
+                let coinId = row.coinId;
+                let resolvedName;
+                if (!coinId) {
+                    const rs = await client.resolve(row.symbol, trace);
+                    const match = asObj(asObj(rs.data).match);
+                    coinId =
+                        rs.ok && match.coinId != null ? String(match.coinId) : undefined;
+                    resolvedName = asStr(match.name);
+                }
+                if (!coinId)
+                    continue;
+                const mk = await client.market(coinId, trace);
+                const m = asObj(mk.data);
+                const price = asObj(m.price);
+                const entry = {
+                    symbol: row.symbol,
+                    coinId,
+                    name: resolvedName ?? row.name ?? undefined,
+                    priceUsd: asNum(price.usd) ?? row.priceUsd,
+                    change1h: asNum(price.change1h),
+                    change24h: asNum(price.change24h) ?? row.change24hPct,
+                    change7d: asNum(price.change7d),
+                    sentimentBullishPct: asNum(asObj(m.sentiment).bullishPct) ?? undefined,
+                    freshness: freshnessOf(asObj(m.observation)),
+                    discovered: true,
+                };
+                if (wantIndicators) {
+                    const ind = await fetchIndicators(client, coinId, trace);
+                    if (ind)
+                        entry.indicators = ind;
+                }
+                watch.push(entry);
+            }
+            const context = rows.slice(UNIVERSE_RESOLVE_TOP);
+            if (context.length > 0)
+                universeMovers = context;
+        }
+    }
     // Spot resting orders (for cancel + affordability) — only if spot is enabled.
     const wantSpot = spec.venues.includes("spot");
     const wantPm = spec.venues.includes("pm");
@@ -451,12 +555,19 @@ export async function observe(client, spec, state, trace) {
         }
     }
     // News context (only with the `news` capability): recent high-importance news
-    // for the watchlist coins, fed into the decide prompt as a market-catalyst
-    // layer the price chart can't show. One cached call; degrades to no news on
-    // failure (never blocks a cycle).
+    // for the coins the agent is actually LOOKING AT this cycle — the watch array,
+    // which includes any `universe_scan`-discovered movers. Keying this to the
+    // static watchlist alone (the old behavior) starved exactly the case news
+    // exists for: a discovered pump whose catalyst the agent is supposed to
+    // investigate before acting (the pump-fade pattern, 2026-08-19). One cached
+    // call; degrades to no news on failure (never blocks a cycle).
     let news;
-    if (wantNews && spec.risk.watchlist.length > 0) {
-        const nr = await client.agentNews({ coins: spec.risk.watchlist.join(","), limit: 8, hours: 48 }, trace);
+    const newsCoins = Array.from(new Set([
+        ...spec.risk.watchlist,
+        ...watch.map((w) => w.symbol.toUpperCase()),
+    ]));
+    if (wantNews && newsCoins.length > 0) {
+        const nr = await client.agentNews({ coins: newsCoins.join(","), limit: 8, hours: 48 }, trace);
         if (nr.ok) {
             news = asArr(asObj(nr.data).items)
                 .map(asObj)
@@ -495,6 +606,7 @@ export async function observe(client, spec, state, trace) {
         syncCursor,
         newClosedTrades,
         polledBeforeWrite,
+        universeMovers,
     };
     // 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.

package/dist/agent/prompt.d.ts

@@ -6,4 +6,6 @@ export declare function buildSystemPrompt(spec: AgentSpec, mergedProse: string,
 export declare function buildUserPrompt(obs: Observation, journal?: Array<{
     at: string;
     did: string;
-}>): string;
+}>, opts?: {
+    venues?: AgentSpec["venues"];
+}): string;