@coinrithm/mcp-trading 0.4.0 → 0.7.0

package/dist/agent/runner.js

@@ -2,11 +2,14 @@
 // 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 { spotBuyCost, DEFAULT_TRIGGER_POLICY, } from "./types.js";
+import { evaluateGate, noteLlmCall, estimateCostUsd } from "./gate.js";
+import { baseSymbol } from "./setups.js";
 import { observe } from "./observe.js";
 import { buildSystemPrompt, buildUserPrompt } from "./prompt.js";
 import { parseDecision } from "./decision.js";
 import { validateAction } from "./decisionValidator.js";
+import { resolvePmRef } from "./resolvePm.js";
 import { fetchQuote, executeAction } from "./act.js";
 import { makeDecisionId, makeTrace, exportRunEvidence } from "./runEvidence.js";
 import { rollDay, checkKillSwitch, accrueRealized, saveState, } from "./state.js";
@@ -52,6 +55,105 @@ function cashConsumed(action, quote) {
     }
     return 0;
 }
+// Orienting a take-profit relative to side + mark is deterministic arithmetic —
+// the runner should OWN it, not trust a weak model to compute it (the same reason
+// pmN offloads the long-id copy). When a futures_open's takeProfitPrice is missing
+// or on the WRONG side (long TP <= mark / short TP >= mark), the server rejects the
+// WHOLE open (take_profit_not_*_mark) — the position never opens, so the model
+// can't "let winners run". Here we substitute a sensible R:R target off the stop so
+// the open succeeds with a valid TP. Only fires when a usable stop is present (so
+// risk is computable) and the TP is actually missing/wrong-side; a correct TP is
+// left untouched. Systemic fix for the whole free-tier 8B/instruct fleet.
+const DEFAULT_TP_RR = 1.5; // reward:risk of the substituted take-profit
+export function repairFuturesTakeProfit(action, quote) {
+    if (action.type !== "futures_open")
+        return { action, repaired: false };
+    const entry = quote?.entryPrice;
+    const sl = action.stopLossPrice;
+    if (typeof entry !== "number" || !Number.isFinite(entry) || entry <= 0)
+        return { action, repaired: false };
+    if (typeof sl !== "number" || !Number.isFinite(sl) || sl <= 0)
+        return { action, repaired: false };
+    const isLong = action.side === "long";
+    const tp = action.takeProfitPrice;
+    const tpValid = typeof tp === "number" &&
+        Number.isFinite(tp) &&
+        tp > 0 &&
+        (isLong ? tp > entry : tp < entry);
+    if (tpValid)
+        return { action, repaired: false };
+    // Stop must be on the correct side to imply a positive risk distance; if it
+    // isn't, leave the action for the validator to reject (don't fabricate).
+    const risk = isLong ? entry - sl : sl - entry;
+    if (!(risk > 0))
+        return { action, repaired: false };
+    const target = isLong
+        ? entry + DEFAULT_TP_RR * risk
+        : entry - DEFAULT_TP_RR * risk;
+    if (!(target > 0))
+        return { action, repaired: false };
+    return { action: { ...action, takeProfitPrice: target }, repaired: true };
+}
+// One-line, human-readable summary of an executed action for the agent's journal
+// (slice-3 memory). Compact so a few entries cost almost nothing in the prompt.
+function summarizeAction(a) {
+    switch (a.type) {
+        case "futures_open":
+            return `opened ${a.side} ${a.symbol} (x${a.leverage}, ${a.marginMusd}mUSD)`;
+        case "futures_close":
+            return `closed pos#${a.positionId}`;
+        case "futures_set_sltp":
+            return `trailed stop on pos#${a.positionId}`;
+        case "spot_order":
+            return `${a.side} ${a.symbol} (${a.orderType})`;
+        case "spot_cancel":
+            return `cancelled order#${a.orderId}`;
+        case "pm_open":
+            return `bet PM ${a.slug} ${a.stakeMusd}mUSD`;
+    }
+}
+// Tokens that identify the MARKET an action is on, for checking a rationale is
+// actually about it. close/sltp/cancel reference a position/order id (not a market
+// name) so they return none and keep their position-management rationale as-is.
+function actionMarketTokens(a) {
+    switch (a.type) {
+        case "futures_open":
+        case "spot_order":
+            return [a.symbol, baseSymbol(a.symbol)];
+        case "pm_open":
+            return [a.source, ...a.slug.split("-").filter((w) => w.length >= 4)];
+        default:
+            return [];
+    }
+}
+// Does the decision rationale plausibly name this action's market? Lenient: any
+// market token present counts. An empty token set (close/sltp/cancel) returns true.
+function rationaleMatchesAction(rationale, a) {
+    const toks = actionMarketTokens(a).filter((t) => t && t.length >= 2);
+    if (toks.length === 0)
+        return true;
+    const lower = rationale.toLowerCase();
+    return toks.some((t) => lower.includes(t.toLowerCase()));
+}
+// The per-trade "why" shown on the Arena floor, kept HONEST about the market it's
+// on. Prefer the model's per-action summary. Else the decision-level rationale —
+// but a MULTI-action decision commits that rationale to its PRIMARY idea, which can
+// contradict a secondary action's market ("reasoning didn't match the selected
+// market"), so attach it only when it names this action's market; otherwise a
+// faithful one-line summary of the move. A single-action decision's rationale IS
+// about that action, so it is always kept (the common case, unchanged).
+export function rationaleForAction(a, decisionRationale, perActionSummary, totalActions) {
+    const perAction = perActionSummary?.trim();
+    if (perAction)
+        return perAction;
+    if (!decisionRationale)
+        return summarizeAction(a);
+    if (totalActions <= 1)
+        return decisionRationale;
+    return rationaleMatchesAction(decisionRationale, a)
+        ? decisionRationale
+        : summarizeAction(a);
+}
 export async function runCycle(deps) {
     const { client, provider, spec, mergedProse, state, live, stateFile } = deps;
     const log = deps.log ?? (() => { });
@@ -84,9 +186,35 @@ export async function runCycle(deps) {
         state.seen.push(`${asStr(asObj(t).venue) ?? "futures"}:${asNum(asObj(t).id) ?? String(asObj(t).id)}`);
     }
     state.seen = state.seen.slice(-500);
+    // Slice-3 reflection: journal closed-trade OUTCOMES (not just opens) so the agent
+    // remembers how its theses RESOLVED — a stop-out it should not revenge-trade, a
+    // winner its style works on. Defensive field reads (the /trades shape varies);
+    // a partial entry is harmless, a missing one is skipped.
+    for (const t of observation.newClosedTrades.slice(-5)) {
+        const o = asObj(t);
+        const sym = asStr(o.symbol) ?? asStr(o.coinSymbol) ?? asStr(o.coinId);
+        const pnl = asNum(o.realizedPnlMusd) ??
+            asNum(o.pnlMusd) ??
+            asNum(o.realizedPnl) ??
+            asNum(o.pnl);
+        const side = asStr(o.side);
+        if (sym || pnl != null) {
+            const did = `closed ${side ?? ""} ${sym ?? "position"}`.trim() +
+                (pnl != null
+                    ? `: ${pnl >= 0 ? "+" : ""}${Math.round(pnl)}mUSD ${pnl >= 0 ? "WIN" : "LOSS"}`
+                    : "");
+            state.journal = [
+                ...(state.journal ?? []),
+                { at: observation.asOf, did },
+            ].slice(-12);
+        }
+    }
     // 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);
+    // not only realized losses. Includes BOTH futures AND prediction-market books —
+    // a PM-only agent (or one with a large PM stake) was previously invisible to the
+    // drawdown stop, so a marking-down PM book could not trip it (P1b).
+    const unrealized = observation.openPositions.reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0) +
+        (observation.pmPositions ?? []).reduce((s, p) => s + (p.unrealizedPnlMusd ?? 0), 0);
     if (spec.killSwitch.maxDrawdownMusd > 0 &&
         state.peakRealizedMusd - (state.realizedPnlMusd + unrealized) >=
             spec.killSwitch.maxDrawdownMusd) {
@@ -108,11 +236,56 @@ export async function runCycle(deps) {
         log(`skip: ${obs.skip}`);
         return { decision: "skip", skipReason: obs.skip, planned: [], live };
     }
+    // GATE (slice 2): only SPEND an LLM call when a deterministic trigger fires — a
+    // flagged entry setup or an open position to manage. No trigger => a cheap
+    // heartbeat (zero tokens). A heartbeat is neither a model reject nor a failure,
+    // so it touches NO kill-switch counter; it just records the cheap cycle.
+    const policy = spec.triggerPolicy ?? DEFAULT_TRIGGER_POLICY;
+    const nowMs = Date.now();
+    const gate = evaluateGate(observation, state, policy, nowMs);
+    const providerName = spec.model?.provider ?? "nvidia";
+    if (!gate.fire) {
+        saveState(stateFile, state);
+        log(`gate: skip (${gate.reason})`);
+        return {
+            decision: "skip",
+            skipReason: gate.reason,
+            planned: [],
+            live,
+            triggerCodes: gate.codes,
+            llmCallMade: false,
+            decisionType: "gate_skip",
+            tokensIn: 0,
+            tokensOut: 0,
+            estimatedCostUsd: 0,
+            writeAttempted: 0,
+            writeAccepted: 0,
+        };
+    }
+    noteLlmCall(state, gate.codes, nowMs);
     // DECIDE
-    const res = await provider.decide({
-        system: buildSystemPrompt(spec, mergedProse),
-        user: buildUserPrompt(observation),
-    });
+    const system = buildSystemPrompt(spec, mergedProse);
+    const user = buildUserPrompt(observation, state.journal);
+    const tokensInEst = Math.round((system.length + user.length) / 4);
+    // Prompt-size + trigger visibility in the live terminal.
+    log(`prompt ~${tokensInEst} tok ` +
+        `(pm ${observation.pmMarkets.length}, trades ${observation.newClosedTrades.length}, watch ${observation.watch.length}, setups ${observation.setups.length}, triggers ${gate.codes.join("|") || "none"})`);
+    const res = await provider.decide({ system, user });
+    // Metering: prefer provider-reported usage; fall back to a chars/4 estimate.
+    const tokensIn = res.ok
+        ? (res.usage?.promptTokens ?? tokensInEst)
+        : tokensInEst;
+    const tokensOut = res.ok
+        ? (res.usage?.completionTokens ?? Math.round(res.text.length / 4))
+        : 0;
+    const estimatedCostUsd = estimateCostUsd(providerName, tokensIn, tokensOut);
+    const meter = {
+        triggerCodes: gate.codes,
+        llmCallMade: true,
+        tokensIn,
+        tokensOut,
+        estimatedCostUsd,
+    };
     if (!res.ok) {
         state.consecutiveModelFailures += 1;
         saveState(stateFile, state);
@@ -123,6 +296,10 @@ export async function runCycle(deps) {
             planned: [],
             modelFailed: true,
             live,
+            ...meter,
+            decisionType: "model_error",
+            writeAttempted: 0,
+            writeAccepted: 0,
         };
     }
     const parsed = parseDecision(res.text);
@@ -133,13 +310,24 @@ export async function runCycle(deps) {
         return {
             decision: "skip",
             skipReason: `model output invalid: ${parsed.error}`,
+            rawModelOutput: res.text.slice(0, 8000),
             planned: [],
             modelFailed: true,
             live,
+            ...meter,
+            decisionType: "model_error",
+            writeAttempted: 0,
+            writeAccepted: 0,
         };
     }
     state.consecutiveModelFailures = 0;
     const decision = parsed.decision;
+    // Reasoning captured for the Arena terminal (keystone transparency): the
+    // model's own analysis this cycle + decision confidence + the full raw text
+    // (capped) for debugging. Shared across the skip + act return paths.
+    const rationale = decision.rationale;
+    const confidence = decision.confidence;
+    const rawModelOutput = res.text.slice(0, 8000);
     if (decision.decision === "skip" || decision.actions.length === 0) {
         state.consecutiveRejectCycles += 1;
         saveState(stateFile, state);
@@ -147,8 +335,15 @@ export async function runCycle(deps) {
         return {
             decision: "skip",
             skipReason: decision.reason ?? "model chose skip",
+            rationale,
+            confidence,
+            rawModelOutput,
             planned: [],
             live,
+            ...meter,
+            decisionType: "skip",
+            writeAttempted: decision.actions.length,
+            writeAccepted: 0,
         };
     }
     // VALIDATE (+ ACT when live). Quote evidence is fetched by the runner.
@@ -166,8 +361,86 @@ export async function runCycle(deps) {
     let anyAccepted = false;
     let anyExecuted = false;
     let anyExecFailed = false;
-    for (const action of decision.actions) {
+    for (let action of decision.actions) {
+        // Resolve a short PM ref (pm1…pmN) to the canonical {source,slug,outcome} BEFORE
+        // any quote/validation. Small models copy a 3-char ref reliably but mis-copy the
+        // long outcomeExternalMarketId; an unknown/missing ref is rejected here with a
+        // clear code instead of crashing the validator on an undefined id.
+        if (action.type === "pm_open") {
+            const resolved = resolvePmRef(action, observation.pmMarkets);
+            if (!resolved.ok) {
+                planned.push({
+                    action,
+                    accepted: false,
+                    code: resolved.code,
+                    reason: resolved.reason,
+                });
+                log(`reject pm_open: ${resolved.code} (${resolved.reason})`);
+                continue;
+            }
+            action = resolved.action;
+            // Anti-churn for PM (the analog of the futures duplicate_intent guard):
+            // block re-betting a market+outcome we ALREADY hold an open position on.
+            // Without this a model re-bets the same mispriced market every cycle (one
+            // agent opened 25 identical bets) — pure churn. The model SEES its holdings
+            // in observation.pmPositions; this enforces it. Bet a DIFFERENT market instead.
+            const pm = resolved.action; // narrowed to pm_open (canonical triple filled)
+            const heldPm = observation.pmPositions.find((p) => (p.source ?? "").toLowerCase() === (pm.source ?? "").toLowerCase() &&
+                (p.slug ?? "").toLowerCase() === (pm.slug ?? "").toLowerCase() &&
+                p.outcomeExternalMarketId === pm.outcomeExternalMarketId);
+            if (heldPm) {
+                planned.push({
+                    action,
+                    accepted: false,
+                    code: "duplicate_intent",
+                    reason: `already hold a PM bet on ${pm.slug} / ${pm.outcomeExternalMarketId} — do not re-bet the same market+outcome (churn); pick a different market or skip`,
+                });
+                log(`reject pm_open: duplicate_intent (hold PM ${pm.slug})`);
+                continue;
+            }
+        }
+        // Anti-churn critic: block re-opening a futures position we ALREADY hold unless
+        // it's a confirmed WINNER with room (a legit scale-in). Stops the re-open-a-
+        // loser / re-open-into-the-cap churn deterministically — before we even spend a
+        // quote — with a clear "duplicate_intent" instead of a cryptic cap reject. The
+        // runner caps remain the backstop; this is the cleaner, earlier stop.
+        if (action.type === "futures_open") {
+            // Bind the narrowed action to a const: `action` is a reassignable loop var
+            // (pm-resolve + the take-profit repair below both write to it), and a later
+            // reassignment would otherwise widen it back to the union inside this
+            // closure's control-flow analysis.
+            const fo = action;
+            const ab = baseSymbol(fo.symbol);
+            const held = observation.openPositions.find((p) => p.venue === "futures" &&
+                p.side === fo.side &&
+                baseSymbol(p.symbol) === ab);
+            if (held) {
+                const winning = (held.unrealizedPnlMusd ?? 0) > 0;
+                const hasRoom = openCount < spec.risk.maxConcurrentPositions &&
+                    openMarginMusd + fo.marginMusd <= spec.limits.maxOpenMarginMusd;
+                if (!(winning && hasRoom)) {
+                    planned.push({
+                        action,
+                        accepted: false,
+                        code: "duplicate_intent",
+                        reason: `already hold ${fo.symbol} ${fo.side}${winning ? " (no margin room to add)" : " — manage it, do not average down or re-open"}`,
+                    });
+                    log(`reject ${action.type}: duplicate_intent (hold ${fo.symbol} ${fo.side})`);
+                    continue;
+                }
+            }
+        }
         const quote = await fetchQuote(client, action, observation, baseTrace);
+        // Auto-clamp a missing/wrong-side futures take-profit to a valid R:R target
+        // off the stop, so the open isn't silently rejected server-side (the runner
+        // owns trigger orientation; weak models routinely mis-sign it).
+        {
+            const fixed = repairFuturesTakeProfit(action, quote);
+            if (fixed.repaired) {
+                action = fixed.action;
+                log(`repaired ${action.type} take-profit -> ${action.takeProfitPrice} (R:R off stop; model TP was missing/wrong-side)`);
+            }
+        }
         const ctx = {
             spec,
             // Inherit the decision-level confidence so the per-action abstention gate
@@ -215,7 +488,13 @@ export async function runCycle(deps) {
         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 trace = makeTrace(runId, decisionId, spec, meta.confidence ?? decision.confidence, 
+        // The trade's "why" on the Arena live floor. Prefer the model's per-action
+        // summary; else the decision rationale, but kept HONEST about this action's
+        // market (a multi-action decision's rationale can be about a DIFFERENT market
+        // than a secondary trade — see rationaleForAction). Sanitized short reasoning
+        // only — never raw chain-of-thought.
+        rationaleForAction(action, decision.rationale, meta.rationaleSummary, decision.actions.length));
         const r = await executeAction(client, action, observation, trace, idem);
         planned.push({
             action,
@@ -253,10 +532,33 @@ export async function runCycle(deps) {
     state.consecutiveExecFailures =
         anyExecFailed && !anyExecuted ? state.consecutiveExecFailures + 1 : 0;
     state.rateLimitHits = client.rateLimitHits ?? state.rateLimitHits;
+    // Slice-3 memory: journal the accepted move(s) + the thesis behind them so next
+    // cycle has continuity (manage with memory of WHY; don't re-open what we just did).
+    const moves = planned
+        .filter((p) => p.accepted)
+        .map((p) => summarizeAction(p.action));
+    if (moves.length > 0) {
+        const did = `${moves.join("; ")}${rationale ? ` — ${rationale.slice(0, 90)}` : ""}`;
+        state.journal = [
+            ...(state.journal ?? []),
+            { at: observation.asOf, did },
+        ].slice(-10);
+    }
     saveState(stateFile, state);
     if (live && anyExecuted)
         await exportRunEvidence(client, runId);
-    return { decision: "act", planned, live };
+    return {
+        decision: "act",
+        rationale,
+        confidence,
+        rawModelOutput,
+        planned,
+        live,
+        ...meter,
+        decisionType: "act",
+        writeAttempted: decision.actions.length,
+        writeAccepted: planned.filter((p) => p.accepted).length,
+    };
 }
 export async function runLoop(deps, opts = {}) {
     const results = [];

package/dist/agent/setups.d.ts

@@ -0,0 +1,3 @@
+import { OpenPosition, SetupSignal, WatchEntry } from "./types.js";
+export declare function baseSymbol(s: string | undefined): string;
+export declare function scanSetups(watch: WatchEntry[], openPositions?: OpenPosition[]): SetupSignal[];

package/dist/agent/setups.js

@@ -0,0 +1,133 @@
+// Deterministic setup scan — the first slice of the preflight gate.
+//
+// The problem it solves: cautious free-tier brains were skipping 100% of cycles
+// with "no clear setup" even while the tape moved 3-4%. The fix (drawn straight
+// from content-engine's gate design): do NOT make the model decide whether a setup
+// exists. Compute it deterministically from the indicators we already have, then
+// hand the flagged setups to the model so it decides HOW to act, not WHETHER
+// anything is happening. This flips the default from "no setup -> skip" to "here
+// is the structure -> trade it (in your style) or give a real reason not to".
+//
+// Pure + stateless: no I/O, no model. Strategy-neutral — it reports the structure
+// and the trend-following bias; a contrarian agent fades the same facts.
+// Thresholds tuned to FIRE readily on a normal moving market (the failure mode we
+// are fixing is under-firing). A genuinely flat tape still yields an empty list,
+// which is the correct "nothing to do" signal.
+const STRONG_MOVE_PCT = 2.0; // |24h %| that counts as a real directional push
+const LEAN_MOVE_PCT = 0.8; // smaller move that still confirms an EMA-stack trend
+const RSI_OVERSOLD = 35;
+const RSI_OVERBOUGHT = 68;
+const MIN_STRENGTH = 0.5; // below this we do not flag (avoid noise)
+function pct(n) {
+    return `${n >= 0 ? "+" : ""}${n.toFixed(1)}%`;
+}
+// Normalize a symbol to its base asset so a watch "BTC" matches an open position
+// "BTC-PERP" / "BTCUSDT" when checking whether we already hold it.
+export function baseSymbol(s) {
+    return (s ?? "")
+        .toUpperCase()
+        .replace(/[-/]?(PERP|USDT|USDC|USD)$/i, "")
+        .replace(/[^A-Z0-9]/g, "");
+}
+// Classify ONE coin into its setups. Usually one (the trend/breakout read), but a
+// TRENDING coin that is also RSI-extreme emits a SECOND, counter-trend "fade"
+// signal — the same structure is a momentum trade to a trend-follower and a
+// mean-reversion trade to a contrarian, so we surface both and let each agent pick
+// the one matching its style (fixes contrarians skipping "no setup fits me").
+function classify(w, openPositions) {
+    const ind = w.indicators;
+    if (!ind)
+        return [];
+    const ch = w.change24h ?? 0;
+    const rsi = ind.rsi14;
+    const up = ind.ema20AboveEma50 === true && ind.aboveEma20 === true;
+    const down = ind.ema20AboveEma50 === false && ind.aboveEma20 === false;
+    const oversold = rsi != null && rsi <= RSI_OVERSOLD;
+    const overbought = rsi != null && rsi >= RSI_OVERBOUGHT;
+    // Compact, factual note the model reads (no interpretation — just the structure).
+    const facts = [`${pct(ch)} 24h`];
+    if (up)
+        facts.push("price>EMA20>EMA50 (uptrend)");
+    else if (down)
+        facts.push("price<EMA20<EMA50 (downtrend)");
+    if (rsi != null)
+        facts.push(`RSI ${Math.round(rsi)}${oversold ? " oversold" : overbought ? " overbought" : ""}`);
+    if (ind.brokeRecentHigh === true)
+        facts.push("broke 20-bar high");
+    if (ind.brokeRecentLow === true)
+        facts.push("broke 20-bar low");
+    if (ind.atr14 != null && ind.asOfClose)
+        facts.push(`ATR ${((100 * ind.atr14) / ind.asOfClose).toFixed(1)}% (stop ~1.5xATR)`);
+    const note = facts.join(" · ");
+    const out = [];
+    // Primary trend-following / breakout read.
+    if (ind.brokeRecentHigh === true) {
+        out.push({ symbol: w.symbol, kind: "breakout", bias: "long", strength: 0.8, note });
+    }
+    else if (ind.brokeRecentLow === true) {
+        out.push({ symbol: w.symbol, kind: "breakdown", bias: "short", strength: 0.8, note });
+    }
+    else if (up && ch >= LEAN_MOVE_PCT) {
+        out.push({ symbol: w.symbol, kind: "uptrend", bias: "long", strength: ch >= STRONG_MOVE_PCT ? 0.75 : 0.6, note });
+    }
+    else if (down && ch <= -LEAN_MOVE_PCT) {
+        out.push({ symbol: w.symbol, kind: "downtrend", bias: "short", strength: ch <= -STRONG_MOVE_PCT ? 0.75 : 0.6, note });
+    }
+    else if (overbought) {
+        out.push({ symbol: w.symbol, kind: "stretched", bias: "fade-short", strength: 0.55, note });
+    }
+    else if (oversold) {
+        out.push({ symbol: w.symbol, kind: "stretched", bias: "fade-long", strength: 0.55, note });
+    }
+    else if (Math.abs(ch) >= STRONG_MOVE_PCT) {
+        // A strong move with no clean EMA stack — still tradeable momentum.
+        out.push({ symbol: w.symbol, kind: ch > 0 ? "uptrend" : "downtrend", bias: ch > 0 ? "long" : "short", strength: 0.55, note });
+    }
+    // Secondary COUNTER-TREND fade: a standing trend that is ALSO RSI-extreme is a
+    // mean-reversion candidate. Only add it when the primary was the trend itself
+    // (so we don't double-list a pure stretched read).
+    const primaryIsTrend = out[0] && (out[0].kind === "uptrend" || out[0].kind === "downtrend" || out[0].kind === "breakout" || out[0].kind === "breakdown");
+    if (primaryIsTrend && (oversold || overbought)) {
+        out.push({
+            symbol: w.symbol,
+            kind: "stretched",
+            bias: oversold ? "fade-long" : "fade-short",
+            strength: 0.6,
+            note: `${note} — counter-trend fade (mean-reversion: ${oversold ? "oversold within downtrend" : "overbought within uptrend"})`,
+        });
+    }
+    // Position awareness: if we already hold this symbol, tag every signal with the
+    // side held AND the position's win/loss state right in the note — so the model
+    // ADDS to a winner (only with free margin), trails, or cuts a loser, instead of
+    // pointlessly re-opening the same size into the margin cap (the open_margin_
+    // exceeds_cap churn). A winner with room is the one case a same-side "open" is OK
+    // (scaling in); otherwise it's manage-only.
+    const wb = baseSymbol(w.symbol);
+    const pos = wb ? openPositions.find((p) => baseSymbol(p.symbol) === wb) : undefined;
+    const held = pos && (pos.side === "long" || pos.side === "short") ? pos.side : undefined;
+    if (held) {
+        const u = pos?.unrealizedPnlMusd;
+        const tag = u == null
+            ? ` [HELD ${held} — manage, do NOT re-open]`
+            : u >= 0
+                ? ` [HELD ${held}, +${Math.round(u)}mUSD WINNER — ADD only if you have free margin (scale into strength), else trail the stop; never re-open the same size]`
+                : ` [HELD ${held}, ${Math.round(u)}mUSD loser — trail or cut; do NOT average down or re-open]`;
+        for (const s of out) {
+            s.held = held;
+            s.note = s.note + tag;
+        }
+    }
+    return out;
+}
+// Scan the whole watchlist, return the flagged setups strongest-first. An empty
+// list = a flat tape = a legitimate reason to skip new entries this cycle. Setups
+// on a symbol we already hold are tagged `held` (manage, don't re-open).
+export function scanSetups(watch, openPositions = []) {
+    const out = [];
+    for (const w of watch) {
+        for (const s of classify(w, openPositions))
+            if (s.strength >= MIN_STRENGTH)
+                out.push(s);
+    }
+    return out.sort((a, b) => b.strength - a.strength);
+}

package/dist/agent/skill.d.ts

@@ -1,4 +1,5 @@
 import { AgentSpec, ParsedSkill, ResolvedAgent, ResolveIssue } from "./types.js";
+export declare const UNLIMITED_TRADES_PER_DAY = 1000000;
 export declare function buildSpec(raw: Record<string, unknown>): AgentSpec;
 export declare function parseSkill(text: string): ParsedSkill;
 export declare function loadSkill(path: string): ParsedSkill;

package/dist/agent/skill.js

@@ -1,14 +1,20 @@
 import { readFileSync } from "node:fs";
 import { parseFrontmatter } from "./frontmatter.js";
-import { VENUES, PROVIDERS, ALLOWED_CAPABILITIES, } from "./types.js";
+import { VENUES, PROVIDERS, ALLOWED_CAPABILITIES, DEFAULT_TRIGGER_POLICY, } 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).
+// A daily TRADE-COUNT cap of 0 (or absent) means UNLIMITED. We don't throttle how often
+// an agent trades — the risk caps (daily loss, open margin, leverage, stops) are the real
+// guardrails. "Unlimited" is normalised to a large finite value so cap-merge arithmetic
+// (most-restrictive-wins) and JSON serialisation stay simple.
+export const UNLIMITED_TRADES_PER_DAY = 1_000_000;
+const normalizeTradeCap = (v) => (v <= 0 ? UNLIMITED_TRADES_PER_DAY : v);
 const DEFAULT_LIMITS = {
-    maxTradesPerDay: 20,
+    maxTradesPerDay: UNLIMITED_TRADES_PER_DAY,
     maxWritesPerCycle: 2,
     maxDailyLossMusd: 5_000,
     maxOpenMarginMusd: 5_000,
@@ -67,6 +73,7 @@ export function buildSpec(raw) {
     const abst = obj(raw.abstention);
     const sync = obj(raw.sync);
     const ks = obj(raw.killSwitch);
+    const trig = obj(raw.triggerPolicy);
     const venues = strArr(raw.venues).filter((v) => VENUES.includes(v));
     return {
         name: typeof raw.name === "string" ? raw.name : "",
@@ -87,7 +94,7 @@ export function buildSpec(raw) {
             blocklist: strArr(risk.blocklist),
         },
         limits: {
-            maxTradesPerDay: num(limits.maxTradesPerDay, DEFAULT_LIMITS.maxTradesPerDay),
+            maxTradesPerDay: normalizeTradeCap(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),
@@ -110,6 +117,17 @@ export function buildSpec(raw) {
         },
         objective: buildObjective(raw.objective),
         capabilities: strArr(raw.capabilities).filter((c) => ALLOWED_CAPABILITIES.includes(c)),
+        // OKF v2 (load-bearing): the gate reads this; omitted -> DEFAULT_TRIGGER_POLICY.
+        // This is the agent's INTENT — the platform deployment overlay may tighten it
+        // server-side, and it can never widen a hard cap (caps live in the runner).
+        triggerPolicy: {
+            mode: trig.mode === "always" ? "always" : DEFAULT_TRIGGER_POLICY.mode,
+            skipLlmWhenNoTrigger: bool(trig.skipLlmWhenNoTrigger, DEFAULT_TRIGGER_POLICY.skipLlmWhenNoTrigger),
+            alwaysManageOpenPositions: bool(trig.alwaysManageOpenPositions, DEFAULT_TRIGGER_POLICY.alwaysManageOpenPositions),
+            maxLlmCallsPerHour: num(trig.maxLlmCallsPerHour, DEFAULT_TRIGGER_POLICY.maxLlmCallsPerHour),
+            debounceMinutes: num(trig.debounceMinutes, DEFAULT_TRIGGER_POLICY.debounceMinutes),
+            pmEvalCooldownMinutes: num(trig.pmEvalCooldownMinutes, DEFAULT_TRIGGER_POLICY.pmEvalCooldownMinutes),
+        },
     };
 }
 export function parseSkill(text) {

package/dist/agent/skillValidator.js

@@ -2,6 +2,8 @@ import { fail, VENUES, PROVIDERS, SPEC_VERSION, OBJECTIVE_PRIMARIES, ALLOWED_CAP
 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;
+// maxTradesPerDay accepts 0 as the explicit "unlimited daily trades" sentinel.
+const isNonNegNum = (v) => typeof v === "number" && Number.isFinite(v) && v >= 0;
 export function validateSkill(parsed, mode = "self-host") {
     const raw = parsed.raw;
     const issues = [];
@@ -99,8 +101,8 @@ export function validateSkill(parsed, mode = "self-host") {
         }
         else {
             const l = raw.limits;
-            if (!isPosNum(l.maxTradesPerDay))
-                add("skill_limits_trades", "limits.maxTradesPerDay must be a positive number");
+            if (!isNonNegNum(l.maxTradesPerDay))
+                add("skill_limits_trades", "limits.maxTradesPerDay must be a number >= 0 (0 = unlimited daily trades)");
             if (!isPosNum(l.maxWritesPerCycle))
                 add("skill_limits_writes", "limits.maxWritesPerCycle must be a positive number");
             if (!isPosNum(l.maxDailyLossMusd))

package/dist/agent/state.js

@@ -77,11 +77,19 @@ export function accrueRealized(state, closedTrades) {
     if (state.realizedPnlMusd > state.peakRealizedMusd)
         state.peakRealizedMusd = state.realizedPnlMusd;
 }
+// A transient model-failure streak (free models occasionally time out/hang) must
+// never disable an agent on a hair-trigger, so the model-failure kill-switch is
+// floored at this many consecutive failures regardless of an agent's own (lower)
+// setting. The scheduler additionally auto-revives any model-failure disable.
+const MODEL_FAILURE_FLOOR = 10;
 // Returns a disable reason if any kill-switch condition is tripped, else null.
 export function checkKillSwitch(spec, state) {
     const ks = spec.killSwitch;
-    if (ks.maxConsecutiveModelFailures > 0 && state.consecutiveModelFailures >= ks.maxConsecutiveModelFailures) {
-        return `consecutive model failures ${state.consecutiveModelFailures} >= ${ks.maxConsecutiveModelFailures}`;
+    if (ks.maxConsecutiveModelFailures > 0) {
+        const threshold = Math.max(ks.maxConsecutiveModelFailures, MODEL_FAILURE_FLOOR);
+        if (state.consecutiveModelFailures >= threshold) {
+            return `consecutive model failures ${state.consecutiveModelFailures} >= ${threshold}`;
+        }
     }
     if (ks.maxConsecutiveRejects > 0 && state.consecutiveRejectCycles >= ks.maxConsecutiveRejects) {
         return `consecutive reject cycles ${state.consecutiveRejectCycles} >= ${ks.maxConsecutiveRejects}`;