@coinrithm/mcp-trading 0.7.15 → 0.7.17

package/dist/agent/decision.js

@@ -1,8 +1,10 @@
+import { parsePmPaperDecision } from "./pmPaperDecision.js";
 // Parse the model's single text response into a strict, structured Decision.
 // Accepts futures + spot + prediction-market actions. Anything else — invalid
 // JSON, an unknown action type, a free-form endpoint/tool name, extra unknown
 // fields, or a missing required field — fails closed (the runner skips).
 import { z } from "zod";
+import JSON5 from "json5";
 import { coerceThesis } from "./thesis.js";
 // Small models (especially Llama 3.1 8B) frequently emit numbers as JSON strings
 // ("12345", "0.8", "62000"). Coerce a *clean* numeric string to a number before
@@ -363,15 +365,95 @@ function coerceJson(text) {
     }
     return JSON.parse(s); // throws on invalid JSON -> caller treats as fail-closed
 }
+// Fixed, non-content diagnostics only. Never retain model text, identifiers,
+// action values or reasoning to investigate a provider's encoding failures.
+export const ACTIONS_STRING_DIAGNOSTICS = [
+    "json_array_empty_valid_decision",
+    "json_array_nonempty_valid_decision",
+    "json_array_invalid_decision",
+    "json_nonarray",
+    "invalid_json",
+    "empty_string_valid_skip",
+    "empty_string_other_decision",
+    "non_json_array_text",
+    "json5_array_valid_decision",
+    "json5_array_invalid_decision",
+    "over_size_limit",
+];
+function diagnoseActionsString(obj) {
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
+        return undefined;
+    const record = obj;
+    if (typeof record.actions !== "string")
+        return undefined;
+    if (record.actions.length > 65_536)
+        return "over_size_limit";
+    const text = record.actions.trim();
+    if (text === "") {
+        return record.decision === "skip" &&
+            decisionSchema.safeParse({ ...record, actions: [] }).success
+            ? "empty_string_valid_skip"
+            : "empty_string_other_decision";
+    }
+    let actions;
+    try {
+        actions = JSON.parse(record.actions);
+    }
+    catch {
+        if (!text.startsWith("["))
+            return "invalid_json";
+        // Diagnostic only: identify alternate literal encodings without accepting
+        // them or retaining content. JSON5 never evaluates expressions. Requiring
+        // finite JSON values keeps Infinity/NaN from looking like usable actions.
+        try {
+            const candidate = JSON5.parse(text);
+            JSON.stringify(candidate, (key, value) => {
+                if (["__proto__", "constructor", "prototype"].includes(key) ||
+                    (typeof value === "number" && !Number.isFinite(value)))
+                    throw new Error("Unsafe diagnostic value");
+                return value;
+            });
+            return Array.isArray(candidate) &&
+                decisionSchema.safeParse({ ...record, actions: candidate }).success
+                ? "json5_array_valid_decision"
+                : "json5_array_invalid_decision";
+        }
+        catch {
+            return "non_json_array_text";
+        }
+    }
+    if (!Array.isArray(actions))
+        return "json_nonarray";
+    if (!decisionSchema.safeParse({ ...record, actions }).success)
+        return "json_array_invalid_decision";
+    return actions.length === 0
+        ? "json_array_empty_valid_decision"
+        : "json_array_nonempty_valid_decision";
+}
+function safeIssueMessage(issue) {
+    // These Zod messages echo model-supplied values or unknown field names.
+    // Other messages in this fixed schema describe types or contract limits.
+    switch (issue.code) {
+        case "invalid_enum_value":
+            return "Invalid enum value";
+        case "invalid_literal":
+            return "Invalid literal value";
+        case "unrecognized_keys":
+            return "Unrecognized field(s)";
+        default:
+            return issue.message;
+    }
+}
 export function parseDecision(text) {
     let obj;
     try {
         obj = normalizeDecisionVerb(coerceJson(text));
     }
-    catch (err) {
+    catch {
         return {
             ok: false,
-            error: `model output is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+            // Node's JSON syntax errors can include excerpts of private model text.
+            error: "model output is not valid JSON",
         };
     }
     const res = decisionSchema.safeParse(obj);
@@ -379,8 +461,9 @@ export function parseDecision(text) {
         return {
             ok: false,
             error: res.error.issues
-                .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+                .map((i) => `${i.path.join(".") || "(root)"}: ${safeIssueMessage(i)}`)
                 .join("; "),
+            actionsStringDiagnostic: diagnoseActionsString(obj),
         };
     }
     const d = res.data;
@@ -397,3 +480,9 @@ export function parseDecision(text) {
         },
     };
 }
+/** Only the trusted host selects a versioned contract; default stays legacy. */
+export function parseDecisionForContract(text, contract) {
+    return contract === "pm_paper_v2"
+        ? parsePmPaperDecision(text)
+        : parseDecision(text);
+}

package/dist/agent/decisionValidator.d.ts

@@ -20,7 +20,38 @@ export interface DecisionContext {
     realizedLossTodayMusd: number;
     targetedPositionIds: number[];
     targetedOrderIds: number[];
+    pmEventsOpenedThisCycle?: string[];
+    pmCoinHorizonsOpenedThisCycle?: PmCoinHorizon[];
+    nowMs?: number;
 }
+/**
+ * Edge (points) risk.pmMinEdgeGapPct requires at a fee-inclusive entry cost:
+ * pct% of the room left to 100. Cost at or above 100 leaves no room, so any
+ * positive gap rule makes the requirement unreachable rather than zero.
+ */
+export declare function requiredGapEdgePoints(entryPct: number, gapPct: number): number;
+/** Ends within this of each other share a coin horizon (venue date splits). */
+export declare const PM_COIN_HORIZON_WINDOW_MS: number;
+/** An end beyond this is a venue sentinel, never a real horizon. */
+export declare const PM_PLAUSIBLE_END_MAX_MS: number;
+export interface PmCoinHorizon {
+    coins: string[];
+    endMs: number;
+}
+/** The later of observation.asOf and the validation clock, when known. */
+export declare function pmReferenceMs(asOf: string, nowMs?: number): number;
+/**
+ * The coin horizon of a market or held position, or null when it cannot be
+ * grouped: no linked coin, or an end that is missing, unparseable, not after
+ * the reference time, or more than 5 years after it (venue sentinels).
+ */
+export declare function pmCoinHorizonOf(item: {
+    coins?: string[];
+    endDate?: string;
+}, refMs: number): PmCoinHorizon | null;
+/** Event key shared by pm_open actions, held positions and markets. */
+export declare function pmEventKey(source: string, slug: string): string;
+export declare const TRIGGER_PRICE_EPS = 1e-8;
 /**
  * True when a thesis says, in so many words, that it is betting AGAINST the
  * outcome the action is buying. Deliberately narrow: it fires only when the

package/dist/agent/decisionValidator.js

@@ -4,6 +4,46 @@
 // market text cannot widen a limit or force a trade. Covers futures + spot + PM.
 import { ok, fail, actionVenue, spotBuyCost, } from "./types.js";
 import { checkEntryPredicates } from "./entryPredicates.js";
+import { universeEntryBlock } from "./universe.js";
+/**
+ * Edge (points) risk.pmMinEdgeGapPct requires at a fee-inclusive entry cost:
+ * pct% of the room left to 100. Cost at or above 100 leaves no room, so any
+ * positive gap rule makes the requirement unreachable rather than zero.
+ */
+export function requiredGapEdgePoints(entryPct, gapPct) {
+    const room = 100 - entryPct;
+    if (room <= 0)
+        return gapPct > 0 ? Number.POSITIVE_INFINITY : 0;
+    return (gapPct / 100) * room;
+}
+/** Ends within this of each other share a coin horizon (venue date splits). */
+export const PM_COIN_HORIZON_WINDOW_MS = 24 * 60 * 60 * 1000;
+/** An end beyond this is a venue sentinel, never a real horizon. */
+export const PM_PLAUSIBLE_END_MAX_MS = 5 * 365 * 24 * 60 * 60 * 1000;
+/** The later of observation.asOf and the validation clock, when known. */
+export function pmReferenceMs(asOf, nowMs) {
+    return Math.max(...[Date.parse(asOf), nowMs ?? NaN].filter((t) => Number.isFinite(t)));
+}
+/**
+ * The coin horizon of a market or held position, or null when it cannot be
+ * grouped: no linked coin, or an end that is missing, unparseable, not after
+ * the reference time, or more than 5 years after it (venue sentinels).
+ */
+export function pmCoinHorizonOf(item, refMs) {
+    const coins = item.coins ?? [];
+    if (coins.length === 0 || !item.endDate || !Number.isFinite(refMs))
+        return null;
+    const endMs = Date.parse(item.endDate);
+    if (!Number.isFinite(endMs) ||
+        endMs <= refMs ||
+        endMs - refMs > PM_PLAUSIBLE_END_MAX_MS)
+        return null;
+    return { coins, endMs };
+}
+/** Event key shared by pm_open actions, held positions and markets. */
+export function pmEventKey(source, slug) {
+    return `${source.toLowerCase()}/${slug.toLowerCase()}`;
+}
 const SERVER_MAX_LEVERAGE = 20;
 // Minimum edge, in probability POINTS, between the model's own forecast for
 // the outcome it is backing and what that outcome currently costs. Live
@@ -20,7 +60,7 @@ const PM_MIN_STAKE_MUSD = 10; // server minimum prediction-market stake
 // Match backend-v2 validateSlTpPrices, including its boundary tolerance. This
 // preflight uses observed evidence only; the API still checks a fresh mark and
 // locked position at execution. Older observations can omit these prices.
-const TRIGGER_PRICE_EPS = 1e-8;
+export const TRIGGER_PRICE_EPS = 1e-8;
 function validateTriggerUpdate(action, pos) {
     // executeAction omits null as well as undefined; neither clears a trigger in
     // this runner. Check the resulting state, including retained protection.
@@ -151,6 +191,9 @@ export function validateAction(action, ctx) {
             return fail("unknown_symbol", `${action.symbol} is not on the watchlist`);
         if (!entry.coinId)
             return fail("unresolved_symbol", `${action.symbol} did not resolve to a coin`);
+        const outsideUniverse = universeEntryBlock(spec, entry);
+        if (outsideUniverse)
+            return fail("outside_universe", `${action.symbol} is ${outsideUniverse}`);
         // A futures_open on a symbol you ALREADY hold is treated as an ADD by the
         // server, which REJECTS any SL/TP on an add (sl_tp_not_supported_on_add) and
         // fails the whole open — the single biggest rejection class (e.g. Sam 61/61).
@@ -267,6 +310,11 @@ export function validateAction(action, ctx) {
             return fail("unknown_symbol", `${action.symbol} is not on the watchlist`);
         if (!entry.coinId)
             return fail("unresolved_symbol", `${action.symbol} did not resolve to a coin`);
+        if (action.side === "buy") {
+            const outside = universeEntryBlock(spec, entry);
+            if (outside)
+                return fail("outside_universe", `${action.symbol} is ${outside}`);
+        }
         if (action.orderType === "limit" &&
             !(typeof action.limitPrice === "number" && action.limitPrice > 0)) {
             return fail("missing_limit_price", "a limit order needs a positive limitPrice");
@@ -333,6 +381,68 @@ export function validateAction(action, ctx) {
         if (!mkt) {
             return fail("pm_market_not_discovered", `${action.source}/${action.slug} is not in the discovered PM markets`);
         }
+        const perEventCap = spec.risk.pmMaxOpenPerEvent;
+        if (perEventCap !== undefined) {
+            if (typeof perEventCap !== "number" ||
+                !Number.isInteger(perEventCap) ||
+                perEventCap < 1) {
+                return fail("pm_event_cap_invalid", `risk.pmMaxOpenPerEvent ${JSON.stringify(perEventCap)} is not a whole number of at least 1`);
+            }
+            const key = pmEventKey(mkt.source, mkt.slug);
+            const held = observation.pmPositions.filter((p) => (p.status ?? "open") === "open" &&
+                p.source !== undefined &&
+                p.slug !== undefined &&
+                pmEventKey(p.source, p.slug) === key).length;
+            const thisCycle = (ctx.pmEventsOpenedThisCycle ?? []).filter((k) => k === key).length;
+            if (held + thisCycle >= perEventCap) {
+                return fail("pm_event_cap", `${held + thisCycle} open bet(s) on ${key} >= per-event cap ${perEventCap}`);
+            }
+        }
+        const coinHorizonCap = spec.risk.pmMaxOpenPerCoinHorizon;
+        if (coinHorizonCap !== undefined) {
+            if (typeof coinHorizonCap !== "number" ||
+                !Number.isInteger(coinHorizonCap) ||
+                coinHorizonCap < 1 ||
+                coinHorizonCap > 50) {
+                return fail("pm_coin_horizon_cap_invalid", `risk.pmMaxOpenPerCoinHorizon ${JSON.stringify(coinHorizonCap)} is not a whole number from 1 to 50`);
+            }
+            const refMs = pmReferenceMs(observation.asOf, ctx.nowMs);
+            const candidate = pmCoinHorizonOf(mkt, refMs);
+            // Unknown coin or end: never grouped, never blocked.
+            if (candidate) {
+                const near = (endMs) => Math.abs(endMs - candidate.endMs) <= PM_COIN_HORIZON_WINDOW_MS;
+                for (const coin of candidate.coins) {
+                    const held = observation.pmPositions.filter((p) => {
+                        if ((p.status ?? "open") !== "open")
+                            return false;
+                        const h = pmCoinHorizonOf(p, refMs);
+                        return !!h && h.coins.includes(coin) && near(h.endMs);
+                    }).length;
+                    const thisCycle = (ctx.pmCoinHorizonsOpenedThisCycle ?? []).filter((h) => h.coins.includes(coin) && near(h.endMs)).length;
+                    if (held + thisCycle >= coinHorizonCap) {
+                        return fail("pm_coin_horizon_cap", `${held + thisCycle} open bet(s) on ${coin} ending within 24 h of ${new Date(candidate.endMs).toISOString()} >= per-coin-horizon cap ${coinHorizonCap}`);
+                    }
+                }
+            }
+        }
+        const closeCutoff = spec.risk.pmMinMinutesToClose;
+        if (closeCutoff !== undefined) {
+            if (typeof closeCutoff !== "number" ||
+                !Number.isFinite(closeCutoff) ||
+                closeCutoff < 0) {
+                return fail("pm_close_cutoff_invalid", `risk.pmMinMinutesToClose ${JSON.stringify(closeCutoff)} is not a non-negative number`);
+            }
+            // Only a KNOWN close can trip the cutoff: venues publish null/sentinel
+            // end dates, and an unparseable one is unknown, never "closing now".
+            const endMs = mkt.endDate ? Date.parse(mkt.endDate) : NaN;
+            const refMs = Math.max(...[Date.parse(observation.asOf), ctx.nowMs ?? NaN].filter((t) => Number.isFinite(t)));
+            if (Number.isFinite(endMs) && Number.isFinite(refMs)) {
+                const minutesLeft = (endMs - refMs) / 60_000;
+                if (minutesLeft < closeCutoff) {
+                    return fail("pm_closes_too_soon", `market closes in ${minutesLeft.toFixed(1)} min, inside the ${closeCutoff} min cutoff`);
+                }
+            }
+        }
         if (action.stakeMusd < PM_MIN_STAKE_MUSD) {
             return fail("pm_stake_below_min", `stake ${action.stakeMusd} < $${PM_MIN_STAKE_MUSD} minimum`);
         }
@@ -393,11 +503,37 @@ export function validateAction(action, ctx) {
         // Forecast consistency. By prompt contract forecastProbability is the
         // model's own probability (1-99) that the outcome IT IS BACKING wins, so
         // buying that outcome only makes sense when the forecast clears what the
-        // market charges for it. An ABSENT forecast still never blocks a bet (the
-        // prompt promises that); a PRESENT one that contradicts the trade does.
+        // market charges for it. A forecast is optional unless a configured edge
+        // rule requires one; a present forecast must satisfy the enforced rules.
         // The API's entryProbability is the RAW mid, and executionModel's effective
         // probability excludes fee. Total stake / net shares is the fee-inclusive
         // break-even cost. Do not guess units or fall back to a discovery mid.
+        const maxEdge = spec.risk.pmMaxEdgePoints;
+        if (!ctx.mechanical && maxEdge !== undefined) {
+            if (typeof maxEdge !== "number" ||
+                !Number.isFinite(maxEdge) ||
+                maxEdge < 0 ||
+                maxEdge > 100) {
+                return fail("pm_max_edge_invalid", `risk.pmMaxEdgePoints ${JSON.stringify(maxEdge)} is not a number between 0 and 100`);
+            }
+            // An overconfidence cap cannot be checked against a missing number.
+            if (action.forecastProbability == null) {
+                return fail("pm_forecast_required", `risk.pmMaxEdgePoints ${maxEdge} needs forecastProbability on every pm_open`);
+            }
+        }
+        const edgeGapPct = spec.risk.pmMinEdgeGapPct;
+        if (!ctx.mechanical && edgeGapPct !== undefined) {
+            if (typeof edgeGapPct !== "number" ||
+                !Number.isFinite(edgeGapPct) ||
+                edgeGapPct < 0 ||
+                edgeGapPct > 100) {
+                return fail("pm_edge_gap_invalid", `risk.pmMinEdgeGapPct ${JSON.stringify(edgeGapPct)} is not a number between 0 and 100`);
+            }
+            // An edge rule cannot be checked against a missing number.
+            if (action.forecastProbability == null) {
+                return fail("pm_forecast_required", `risk.pmMinEdgeGapPct ${edgeGapPct} needs forecastProbability on every pm_open`);
+            }
+        }
         if (!ctx.mechanical && action.forecastProbability != null) {
             const stake = ctx.quote.stakeMusd;
             const shares = ctx.quote.sharesEstimate;
@@ -418,6 +554,15 @@ export function validateAction(action, ctx) {
             if (edge + 1e-9 < PM_MIN_FORECAST_EDGE_POINTS) {
                 return fail("forecast_no_positive_edge", `forecast ${action.forecastProbability} vs entry ${entryPct.toFixed(1)} = ${edge.toFixed(1)}pt edge, under the ${PM_MIN_FORECAST_EDGE_POINTS}pt minimum`);
             }
+            if (maxEdge !== undefined && edge > maxEdge + 1e-9) {
+                return fail("pm_edge_overconfident", `forecast ${action.forecastProbability} vs entry ${entryPct.toFixed(1)} = ${edge.toFixed(1)}pt edge, over the ${maxEdge}pt cap`);
+            }
+            if (edgeGapPct !== undefined) {
+                const required = requiredGapEdgePoints(entryPct, edgeGapPct);
+                if (edge + 1e-9 < required) {
+                    return fail("pm_edge_below_gap_rule", `forecast ${action.forecastProbability} vs entry ${entryPct.toFixed(1)} = ${edge.toFixed(1)}pt edge, under the ${required.toFixed(1)}pt required by ${edgeGapPct}% of the gap to 100`);
+                }
+            }
         }
         if (thesisContradictsOutcome(action.thesis?.summary, mkt.outcomeName)) {
             return fail("thesis_action_conflict", `thesis bets against ${mkt.outcomeName}, which this action buys`);

package/dist/agent/engine.d.ts

@@ -1,9 +1,9 @@
 export { runCycle, type RunnerDeps } from "./runner.js";
 export { buildAgentDefinitionSnapshot, type AgentDefinitionSnapshot, } from "./definitionSnapshot.js";
 export { DECISION_INPUT_MAX_BYTES, sanitizeDecisionInputRecord, type DecisionInputRecord, } from "./decisionReceipt.js";
-export { selectProvider, providerForRoute, classifyProviderFailure, 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 { selectProvider, providerForRoute, classifyProviderFailure, anthropicUsage, type ProviderUsage, type ProviderEnv, type ProviderRouteOptions, type Provider, type DecideInput, type DecideResult, type DecideRouteAttempt, type DecideRouteMeta, } from "./providers.js";
+export { parseDecision, parseDecisionForContract, ACTIONS_STRING_DIAGNOSTICS, type ActionsStringDiagnostic, } from "./decision.js";
+export { chatShapeFor, buildChatBody, canRetrySuperToolOutput, 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";
@@ -14,3 +14,5 @@ export { makeRunId } from "./runEvidence.js";
 export { parseCadenceMs } from "./util.js";
 export { BENCHMARK_AGENTS, BENCHMARK_STRATEGIES, decideMechanical, isBenchmarkStrategy, type BenchmarkStrategy, type BenchmarkAgentDefinition, } from "./mechanical.js";
 export type { AgentSpec, RunState, CycleResult, OpportunityReport, PostedOpportunity, PlannedAction, Venue, ProviderName, ModelConfig, } from "./types.js";
+export { readPmHousePolicies, selectPmHousePolicy, type PmHousePolicy, } from "./pmPaperPolicy.js";
+export { runPmPaperCycle, type PmPaperCycleResult } from "./pmPaperCycle.js";

package/dist/agent/engine.js

@@ -8,12 +8,12 @@
 export { runCycle } from "./runner.js";
 export { buildAgentDefinitionSnapshot, } from "./definitionSnapshot.js";
 export { DECISION_INPUT_MAX_BYTES, sanitizeDecisionInputRecord, } from "./decisionReceipt.js";
-export { selectProvider, providerForRoute, classifyProviderFailure, } from "./providers.js";
-export { parseDecision } from "./decision.js";
+export { selectProvider, providerForRoute, classifyProviderFailure, anthropicUsage, } from "./providers.js";
+export { parseDecision, parseDecisionForContract, ACTIONS_STRING_DIAGNOSTICS, } 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 { chatShapeFor, buildChatBody, canRetrySuperToolOutput, } from "./providerCapabilities.js";
 export { probeDecisionContract, } from "./decisionProbe.js";
 export { CoinRithmClient } from "./client.js";
 export { loadAgent, buildSpec } from "./skill.js";
@@ -25,3 +25,5 @@ export { parseCadenceMs } from "./util.js";
 // Mechanical BENCHMARK baseline agents (sol #7): the deterministic, non-LLM
 // reference line the scheduler seeds into agent_runtime and the runner executes.
 export { BENCHMARK_AGENTS, BENCHMARK_STRATEGIES, decideMechanical, isBenchmarkStrategy, } from "./mechanical.js";
+export { readPmHousePolicies, selectPmHousePolicy, } from "./pmPaperPolicy.js";
+export { runPmPaperCycle } from "./pmPaperCycle.js";

package/dist/agent/futuresCloseOutcome.d.ts

@@ -0,0 +1,19 @@
+import type { ApiResult, ProposedAction } from "./types.js";
+/** Future v2 producer contract; legacy responses retain their existing res.ok
+ * meaning. A filled exit closes exposure, even while accounting remains pending. */
+export declare function executionOutcome(action: ProposedAction, result: ApiResult): {
+    executed: boolean;
+    pending: boolean;
+    newWrite: boolean;
+    v2: boolean;
+    replayed: boolean;
+};
+export declare function exitOutcomeMetadata(outcome: ReturnType<typeof executionOutcome>): {
+    executionPending: boolean;
+    executionReplayed: boolean;
+    writeRecorded: boolean;
+} | {
+    executionPending?: undefined;
+    executionReplayed?: undefined;
+    writeRecorded?: undefined;
+};

package/dist/agent/futuresCloseOutcome.js

@@ -0,0 +1,54 @@
+import { asObj } from "./extract.js";
+/** Future v2 producer contract; legacy responses retain their existing res.ok
+ * meaning. A filled exit closes exposure, even while accounting remains pending. */
+export function executionOutcome(action, result) {
+    const body = asObj(result.data);
+    if (action.type !== "futures_close" ||
+        body.executionModel !== "hl_paper_v2") {
+        return {
+            executed: result.ok,
+            pending: false,
+            newWrite: result.ok,
+            v2: false,
+            replayed: false,
+        };
+    }
+    const intent = asObj(body.intent);
+    const common = result.ok &&
+        Number.isSafeInteger(body.positionId) &&
+        body.positionId === action.positionId &&
+        (action.fraction === undefined || action.fraction === 1) &&
+        body.accepted === true &&
+        typeof body.replayed === "boolean" &&
+        typeof intent.id === "string" &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(intent.id);
+    const pending = !!common &&
+        result.status === 202 &&
+        body.executed === false &&
+        typeof intent.status === "string" &&
+        typeof body.accountingStatus === "string" &&
+        ["pending", "leased", "retry", "manual_attention"].includes(intent.status) &&
+        ["open", "pending", "manual_attention"].includes(body.accountingStatus);
+    const executed = !!common &&
+        result.status === 200 &&
+        body.executed === true &&
+        intent.status === "filled" &&
+        typeof body.accountingStatus === "string" &&
+        ["pending", "settled", "manual_attention"].includes(body.accountingStatus);
+    return {
+        executed,
+        pending,
+        newWrite: (executed || pending) && body.replayed === false,
+        v2: true,
+        replayed: body.replayed === true,
+    };
+}
+export function exitOutcomeMetadata(outcome) {
+    return outcome.v2
+        ? {
+            executionPending: outcome.pending,
+            executionReplayed: outcome.replayed,
+            writeRecorded: outcome.newWrite,
+        }
+        : {};
+}

package/dist/agent/futuresEligibility.d.ts

@@ -34,3 +34,16 @@ export interface FuturesEntryPreflightRejection {
  * - referenceRequired false.
  */
 export declare function futuresEntryPreflight(action: ProposedAction, observation: Observation): FuturesEntryPreflightRejection | null;
+/** Prompt-only choices from the SAME reference preflight, not trade approval.
+ * Keep unknown evidence and held-position exceptions distinct from eligibility.
+ * Watch rows, setup receipts and all execution/risk checks remain unchanged. */
+export declare function futuresEntryChoices(observation: Observation): {
+    candidates: Array<{
+        symbol: string;
+        reference: "eligible" | "unknown" | "not_required" | "held_position";
+    }>;
+    blocked: Array<{
+        symbol: string;
+        code: FuturesEntryPreflightRejection["code"];
+    }>;
+};

package/dist/agent/futuresEligibility.js

@@ -66,11 +66,17 @@ export function futuresEntryEligibilityOf(marketContext) {
 export function futuresEntryPreflight(action, observation) {
     if (action.type !== "futures_open")
         return null;
-    const base = baseSymbol(action.symbol);
-    const holdsCoin = (observation.openPositions ?? []).some((p) => p.venue === "futures" &&
+    return futuresReferenceBlock(action.symbol, observation);
+}
+function holdsFutures(symbol, observation) {
+    const base = baseSymbol(symbol);
+    return (observation.openPositions ?? []).some((p) => p.venue === "futures" &&
         (p.status ?? "open") === "open" &&
         baseSymbol(p.symbol) === base);
-    if (holdsCoin)
+}
+function futuresReferenceBlock(symbol, observation) {
+    const base = baseSymbol(symbol);
+    if (holdsFutures(symbol, observation))
         return null;
     const entry = observation.watch.find((w) => baseSymbol(w.symbol) === base);
     const e = entry?.futuresEntryEligibility;
@@ -80,11 +86,43 @@ export function futuresEntryPreflight(action, observation) {
     if (e.status === "reference_stale") {
         return {
             code: "futures_reference_stale",
-            reason: `${action.symbol}: the perpetual reference${e.venue ? ` (${e.venue})` : ""} is stale or unusable for a NEW futures open${when} (too old, or its refresh time is missing, invalid or in the future); the server would refuse it (perpetual_reference_stale). Trade another coin or wait for a fresh reference.`,
+            reason: `${symbol}: the perpetual reference${e.venue ? ` (${e.venue})` : ""} is stale or unusable for a NEW futures open${when} (too old, or its refresh time is missing, invalid or in the future); the server would refuse it (perpetual_reference_stale). Trade another coin or wait for a fresh reference.`,
         };
     }
     return {
         code: "futures_reference_unavailable",
-        reason: `${action.symbol}: CoinRithm has no supported perpetual reference for this coin${when}, so the server refuses a NEW futures open (perpetual_reference_unavailable). Use spot for it, or another coin for futures.`,
+        reason: `${symbol}: CoinRithm has no supported perpetual reference for this coin${when}, so the server refuses a NEW futures open (perpetual_reference_unavailable). Use spot for it, or another coin for futures.`,
     };
 }
+/** Prompt-only choices from the SAME reference preflight, not trade approval.
+ * Keep unknown evidence and held-position exceptions distinct from eligibility.
+ * Watch rows, setup receipts and all execution/risk checks remain unchanged. */
+export function futuresEntryChoices(observation) {
+    const candidates = [];
+    const blocked = [];
+    const seen = new Set();
+    for (const entry of observation.watch) {
+        const base = baseSymbol(entry.symbol);
+        if (seen.has(base))
+            continue;
+        seen.add(base);
+        const rejection = futuresReferenceBlock(entry.symbol, observation);
+        if (rejection) {
+            blocked.push({ symbol: entry.symbol, code: rejection.code });
+        }
+        else {
+            const e = entry.futuresEntryEligibility;
+            candidates.push({
+                symbol: entry.symbol,
+                reference: holdsFutures(entry.symbol, observation)
+                    ? "held_position"
+                    : !e
+                        ? "unknown"
+                        : !e.referenceRequired
+                            ? "not_required"
+                            : "eligible",
+            });
+        }
+    }
+    return { candidates, blocked };
+}

package/dist/agent/observe.d.ts

@@ -1,5 +1,5 @@
 import { CoinRithmClient } from "./client.js";
-import { AgentSpec, RunState, Observation, AgentTrace, PmCalibration, WhaleContext } from "./types.js";
+import { AgentSpec, RunState, Observation, PmMarket, OpenInterestContext, PositioningContext, LiquidationContext, MacroContext, ChainTvlContext, StablecoinSupplyContext, DepthContext, FundingByVenueContext, AgentTrace, PmCalibration, WhaleContext } from "./types.js";
 export interface ObserveOutput {
     observation: Observation;
     skip?: string;
@@ -16,4 +16,30 @@ export declare function isCalibrationChurnMarket(market: {
     slug?: string;
     title?: string;
 }): boolean;
-export declare function observe(client: CoinRithmClient, spec: AgentSpec, state: RunState, trace?: AgentTrace): Promise<ObserveOutput>;
+export declare function openInterestOf(m: Record<string, unknown>, nowMs?: number): OpenInterestContext | undefined;
+export declare function positioningOf(m: Record<string, unknown>, nowMs?: number): PositioningContext | undefined;
+export declare function liquidationsOf(m: Record<string, unknown>, nowMs?: number): LiquidationContext | undefined;
+/**
+ * `{ coins }` from an additive `relatedCoins` array (direct coin slugs), or
+ * nothing: non-arrays and non-string/blank entries are dropped, duplicates
+ * merged. Every valid slug is kept: the API never truncates the list, and
+ * dropping a linked coin could let a bet bypass that coin's cap. An empty
+ * result adds no field.
+ */
+export declare function coinsField(value: unknown): {
+    coins?: string[];
+};
+export declare function fundingByVenueOf(m: Record<string, unknown>, nowMs?: number): FundingByVenueContext | undefined;
+export declare function depthOf(m: Record<string, unknown>, nowMs?: number): DepthContext | undefined;
+export declare function chainTvlOf(m: Record<string, unknown>, nowMs?: number): ChainTvlContext | undefined;
+export declare function stablecoinSupplyOf(m: Record<string, unknown>, nowMs?: number): StablecoinSupplyContext | undefined;
+export declare function macroOf(m: Record<string, unknown>, nowMs?: number): MacroContext | undefined;
+export declare function expandPmMarkets(discData: unknown, heldPmKeys: Set<string>): Omit<PmMarket, "ref">[];
+/** Bench-only observation overrides; live callers pass none. */
+export interface ObserveOptions {
+    /** Read the curated PM board (depth 30, churn removed, calibration read)
+     *  even for a mechanical spec, so a bench baseline sees the recorded
+     *  agent opportunity set. Default: non-mechanical only. */
+    curatedPmBoard?: boolean;
+}
+export declare function observe(client: CoinRithmClient, spec: AgentSpec, state: RunState, trace?: AgentTrace, options?: ObserveOptions): Promise<ObserveOutput>;