@coinrithm/mcp-trading 0.7.16 → 0.7.18

package/dist/agent/capitalSizing.d.ts

@@ -1,6 +1,15 @@
-import type { AgentSpec, CapitalBook, CapitalSizingAdjustment, Observation, ProposedAction, QuoteEvidence } from "./types.js";
+import type { AgentSpec, CapitalBook, CapitalSizingPolicy, CapitalSizingAdjustment, Observation, ProposedAction, QuoteEvidence } from "./types.js";
 export declare const CAPITAL_VALUATION_BASIS = "wallet_assets_spot_marked_futures_pm_at_collateral";
 export declare const CAPITAL_FEE_BUFFER_BPS = 10;
+/** The ticket and stop-risk limits for one action. Owner 2026-10-08: a
+ * risk-taker may size a futures entry it rates at or above
+ * highConviction.minConfidence far above its base ticket. Only futures_open
+ * qualifies; PM and spot sizing never read confidence. */
+export declare function capitalLimitsFor(policy: CapitalSizingPolicy, action: ProposedAction): {
+    perTicketCapitalPct: number;
+    futuresRiskPct: number;
+    highConviction: boolean;
+};
 /** Reconcile the bounded open-position reads against the wallet's frozen
  * buckets. A full page is not assumed complete: the collateral checksums must
  * agree. No held mark, unknown status, missing bucket, or mismatched book can

package/dist/agent/capitalSizing.js

@@ -16,6 +16,28 @@ const FROZEN_RESIDUE_TOLERANCE = 1e-8;
 const centsDown = (n) => Math.floor(n * 100) / 100;
 const positive = (n) => asNum(n) !== undefined && n > 0;
 const nonnegative = (n) => asNum(n) !== undefined && n >= 0;
+/** The ticket and stop-risk limits for one action. Owner 2026-10-08: a
+ * risk-taker may size a futures entry it rates at or above
+ * highConviction.minConfidence far above its base ticket. Only futures_open
+ * qualifies; PM and spot sizing never read confidence. */
+export function capitalLimitsFor(policy, action) {
+    const hc = policy.highConviction;
+    if (hc &&
+        action.type === "futures_open" &&
+        typeof action.confidence === "number" &&
+        Number.isFinite(action.confidence) &&
+        action.confidence >= hc.minConfidence)
+        return {
+            perTicketCapitalPct: hc.perTicketCapitalPct,
+            futuresRiskPct: hc.futuresRiskPct,
+            highConviction: true,
+        };
+    return {
+        perTicketCapitalPct: policy.perTicketCapitalPct,
+        futuresRiskPct: policy.futuresRiskPct,
+        highConviction: false,
+    };
+}
 /** Reconcile the bounded open-position reads against the wallet's frozen
  * buckets. A full page is not assumed complete: the collateral checksums must
  * agree. No held mark, unknown status, missing bucket, or mismatched book can
@@ -119,6 +141,7 @@ export function prepareCapitalAction(action, spec, observation, budget) {
     if (validateCapitalSizingPolicy(spec.capitalSizing).length > 0)
         return { action, rejection: "capital_policy_invalid" };
     const policy = spec.capitalSizing;
+    const limits = capitalLimitsFor(policy, action);
     const adjustment = {
         version: policy.version,
         basis: "owned_collateral_spot_marked_negative_position_marks_only",
@@ -134,7 +157,7 @@ export function prepareCapitalAction(action, spec, observation, budget) {
         !nonnegative(budget.openMarginMusd))
         return reject("capital_budget_unavailable");
     adjustment.conservativeEquityMusd = equity;
-    const ticket = Math.min(spec.risk.perTradeMarginMusd, (equity * policy.perTicketCapitalPct) / 100);
+    const ticket = Math.min(spec.risk.perTradeMarginMusd, (equity * limits.perTicketCapitalPct) / 100);
     const room = Math.min(ticket, (equity * policy.totalCapitalPct) / 100 - budget.committedCapitalMusd, budget.cashAvailableMusd - (equity * policy.cashReservePct) / 100);
     if (!positive(room))
         return reject("capital_allocation_or_reserve_exhausted");
@@ -161,7 +184,7 @@ export function prepareCapitalAction(action, spec, observation, budget) {
     const distance = Math.abs(mark - stop) / mark;
     const fee = CAPITAL_FEE_BUFFER_BPS / 10_000;
     const riskPerMargin = action.leverage * (distance + fee * (1 + stop / mark));
-    const riskBudget = (equity * policy.futuresRiskPct) / 100;
+    const riskBudget = (equity * limits.futuresRiskPct) / 100;
     const margin = centsDown(Math.min(ticket, riskBudget / riskPerMargin, spec.limits.maxOpenMarginMusd - budget.openMarginMusd, room / (1 + action.leverage * fee)));
     Object.assign(adjustment, {
         proposedAmountMusd: action.marginMusd,
@@ -188,6 +211,7 @@ export function validateCapitalAction(action, spec, observation, budget, quote)
         !nonnegative(budget.committedCapitalMusd) ||
         !nonnegative(budget.openMarginMusd))
         return "capital_budget_unavailable";
+    const limits = capitalLimitsFor(p, action);
     let cost, allocated;
     if (action.type === "pm_open") {
         cost = allocated = action.stakeMusd;
@@ -227,7 +251,7 @@ export function validateCapitalAction(action, spec, observation, budget, quote)
         const reward = (notional * favorable) / entry -
             entryFee -
             ((notional * target) / entry) * feeRate;
-        if (risk > (equity * p.futuresRiskPct) / 100 + 1e-8)
+        if (risk > (equity * limits.futuresRiskPct) / 100 + 1e-8)
             return "capital_quote_stop_risk_exceeded";
         if (reward / risk + 1e-8 < p.minRewardRisk)
             return "capital_quote_reward_risk_too_low";
@@ -235,7 +259,7 @@ export function validateCapitalAction(action, spec, observation, budget, quote)
     if (!positive(cost) || !positive(allocated))
         return "capital_quote_cost_evidence_missing";
     if (cost >
-        Math.min(spec.risk.perTradeMarginMusd, (equity * p.perTicketCapitalPct) / 100) +
+        Math.min(spec.risk.perTradeMarginMusd, (equity * limits.perTicketCapitalPct) / 100) +
             1e-8)
         return "capital_ticket_cap_exceeded";
     if (budget.committedCapitalMusd + cost >

package/dist/agent/client.d.ts

@@ -1,3 +1,4 @@
+import { type PmPaperOpen, type PmPaperClose } from "../pmPaperV2.js";
 import { AgentTrace, ApiResult } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://api.coinrithm.com";
 export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
@@ -86,6 +87,10 @@ export declare class CoinRithmClient {
         side: string;
         quantity: number;
     }, trace?: AgentTrace): Promise<ApiResult>;
+    discoverPmPaperV2(query?: {
+        q?: string;
+        limit?: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
     discoverPmMarkets(query?: {
         q?: string;
         source?: string;
@@ -143,6 +148,14 @@ export declare class CoinRithmClient {
         agentTrace?: AgentTrace;
     }): Promise<ApiResult>;
     cancelSpotOrder(orderId: number, idempotencyKey?: string, trace?: AgentTrace): Promise<ApiResult>;
+    openPmPaperV2(body: PmPaperOpen): Promise<ApiResult>;
+    replayPmPaperV2Open(body: PmPaperOpen): Promise<ApiResult>;
+    closePmPaperV2(body: PmPaperClose): Promise<ApiResult>;
+    pmPaperV2Positions(query?: {
+        status?: "open";
+        beforeId?: number;
+        limit?: number;
+    }): Promise<ApiResult>;
     openPmPosition(body: {
         source: string;
         slug: string;

package/dist/agent/client.js

@@ -1,9 +1,4 @@
-// Thin CoinRithm agent-API client for the runner (futures-focused v1).
-//
-// Auth: the user's own crk_live_ key from COINRITHM_API_KEY (env only — never
-// from an agent file). 429 backs off on Retry-After; 401/403/409/422 are
-// FAIL-CLOSED cycle outcomes (returned, not retried). fetch + sleep are
-// injectable so tests run with no network and no real waits.
+import { PM_PAPER_V2_BASE, } from "../pmPaperV2.js";
 import { createHash } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
 import { retryAfterSeconds } from "../retryAfter.js";
@@ -328,6 +323,9 @@ export class CoinRithmClient {
         });
     }
     // ── prediction markets ───────────────────────────────────────────────────
+    discoverPmPaperV2(query, trace) {
+        return this.request("GET", "/api/agent/pm/v2/discover", { query, trace });
+    }
     discoverPmMarkets(query, trace) {
         return this.request("GET", "/api/agent/pm/discover", { query, trace });
     }
@@ -367,6 +365,19 @@ export class CoinRithmClient {
             trace,
         });
     }
+    // Explicit opt-in contract; API derives and authorizes the configured house tuple.
+    openPmPaperV2(body) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/open`, { body });
+    }
+    replayPmPaperV2Open(body) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/open/replay`, { body });
+    }
+    closePmPaperV2(body) {
+        return this.request("POST", `${PM_PAPER_V2_BASE}/close`, { body });
+    }
+    pmPaperV2Positions(query) {
+        return this.request("GET", `${PM_PAPER_V2_BASE}/positions`, { query });
+    }
     openPmPosition(body) {
         return this.request("POST", "/api/agent/pm/open", { body });
     }

package/dist/agent/decision.d.ts

@@ -13,24 +13,24 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     thesis: z.ZodOptional<z.ZodEffects<z.ZodAny, import("./types.js").Thesis | undefined, any>>;
 }, "strict", z.ZodTypeAny, {
     symbol: string;
-    side: "long" | "short";
     type: "futures_open";
+    side: "long" | "short";
+    thesis?: import("./types.js").Thesis | undefined;
     leverage?: any;
     marginMusd?: any;
     stopLossPrice?: any;
     takeProfitPrice?: any;
-    thesis?: import("./types.js").Thesis | undefined;
     confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     symbol: string;
-    side: "long" | "short";
     type: "futures_open";
+    side: "long" | "short";
+    thesis?: any;
     leverage?: unknown;
     marginMusd?: unknown;
     stopLossPrice?: unknown;
     takeProfitPrice?: unknown;
-    thesis?: any;
     confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
@@ -42,16 +42,16 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     thesis: z.ZodOptional<z.ZodEffects<z.ZodAny, import("./types.js").Thesis | undefined, any>>;
 }, "strict", z.ZodTypeAny, {
     type: "futures_close";
+    thesis?: import("./types.js").Thesis | undefined;
     positionId?: any;
     fraction?: any;
-    thesis?: import("./types.js").Thesis | undefined;
     confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     type: "futures_close";
+    thesis?: any;
     positionId?: unknown;
     fraction?: unknown;
-    thesis?: any;
     confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
@@ -64,18 +64,18 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     thesis: z.ZodOptional<z.ZodEffects<z.ZodAny, import("./types.js").Thesis | undefined, any>>;
 }, "strict", z.ZodTypeAny, {
     type: "futures_set_sltp";
+    thesis?: import("./types.js").Thesis | undefined;
+    positionId?: any;
     stopLossPrice?: any;
     takeProfitPrice?: any;
-    positionId?: any;
-    thesis?: import("./types.js").Thesis | undefined;
     confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     type: "futures_set_sltp";
+    thesis?: any;
+    positionId?: unknown;
     stopLossPrice?: unknown;
     takeProfitPrice?: unknown;
-    positionId?: unknown;
-    thesis?: any;
     confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
@@ -91,24 +91,24 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     thesis: z.ZodOptional<z.ZodEffects<z.ZodAny, import("./types.js").Thesis | undefined, any>>;
 }, "strict", z.ZodTypeAny, {
     symbol: string;
+    type: "spot_order";
     side: "buy" | "sell";
     orderType: "limit" | "market" | "stop";
-    type: "spot_order";
+    thesis?: import("./types.js").Thesis | undefined;
     quantity?: any;
     limitPrice?: any;
     stopPrice?: any;
-    thesis?: import("./types.js").Thesis | undefined;
     confidence?: any;
     rationaleSummary?: string | undefined;
 }, {
     symbol: string;
+    type: "spot_order";
     side: "buy" | "sell";
     orderType: "limit" | "market" | "stop";
-    type: "spot_order";
+    thesis?: any;
     quantity?: unknown;
     limitPrice?: unknown;
     stopPrice?: unknown;
-    thesis?: any;
     confidence?: unknown;
     rationaleSummary?: string | undefined;
 }>, z.ZodObject<{
@@ -145,9 +145,9 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     source?: string | undefined;
     slug?: string | undefined;
     outcomeExternalMarketId?: string | undefined;
-    stakeMusd?: any;
     forecastProbability?: number | undefined;
     thesis?: import("./types.js").Thesis | undefined;
+    stakeMusd?: any;
     confidence?: any;
     rationaleSummary?: string | undefined;
     ref?: string | undefined;
@@ -156,9 +156,9 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
     source?: string | undefined;
     slug?: string | undefined;
     outcomeExternalMarketId?: string | undefined;
-    stakeMusd?: unknown;
     forecastProbability?: any;
     thesis?: any;
+    stakeMusd?: unknown;
     confidence?: unknown;
     rationaleSummary?: string | undefined;
     ref?: string | undefined;
@@ -548,3 +548,8 @@ export type ParseDecisionResult = {
     actionsStringDiagnostic?: ActionsStringDiagnostic;
 };
 export declare function parseDecision(text: string): ParseDecisionResult;
+/** Only the trusted host selects a versioned contract; default stays legacy. */
+export declare function parseDecisionForContract(text: string, contract?: "pm_paper_v2"): ParseDecisionResult | {
+    ok: true;
+    decision: z.infer<typeof import("./pmPaperDecision.js").pmPaperDecisionSchema>;
+};

package/dist/agent/decision.js

@@ -1,3 +1,4 @@
+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
@@ -479,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

@@ -51,6 +51,7 @@ export declare function pmCoinHorizonOf(item: {
 }, 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

@@ -60,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.

package/dist/agent/engine.d.ts

@@ -2,7 +2,7 @@ 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, anthropicUsage, type ProviderUsage, type ProviderEnv, type ProviderRouteOptions, type Provider, type DecideInput, type DecideResult, type DecideRouteAttempt, type DecideRouteMeta, } from "./providers.js";
-export { parseDecision, ACTIONS_STRING_DIAGNOSTICS, type ActionsStringDiagnostic, } from "./decision.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";
@@ -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

@@ -9,7 +9,7 @@ export { runCycle } from "./runner.js";
 export { buildAgentDefinitionSnapshot, } from "./definitionSnapshot.js";
 export { DECISION_INPUT_MAX_BYTES, sanitizeDecisionInputRecord, } from "./decisionReceipt.js";
 export { selectProvider, providerForRoute, classifyProviderFailure, anthropicUsage, } from "./providers.js";
-export { parseDecision, ACTIONS_STRING_DIAGNOSTICS, } from "./decision.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).
@@ -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, OpenInterestContext, PositioningContext, LiquidationContext, MacroContext, ChainTvlContext, StablecoinSupplyContext, DepthContext, FundingByVenueContext, 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;
@@ -34,6 +34,7 @@ export declare function depthOf(m: Record<string, unknown>, nowMs?: number): Dep
 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)

package/dist/agent/observe.js

@@ -967,7 +967,7 @@ function titleMentionsCoin(title, symbol) {
 // backend flagged not-openable (eligible === false) and markets the agent already
 // holds (heldPmKeys). Shared by the primary board fetch and the crypto-targeted
 // secondary fetch so both go through the exact same filters.
-function expandPmMarkets(discData, heldPmKeys) {
+export function expandPmMarkets(discData, heldPmKeys) {
     const dd = asObj(discData);
     return (asArr(dd.data ?? dd.markets ?? dd.results)
         .map(asObj)

package/dist/agent/pmPaperCandidates.d.ts

@@ -0,0 +1,17 @@
+/** Immutable entry identity excludes aliases and the opposite order side.
+ * Unknown identities hold new entries, but do not block closing/replaying. */
+export declare function pmHeldNativeMarkets(positions: readonly unknown[]): {
+    keys: Set<string>;
+    complete: boolean;
+};
+export declare function pmCandidateWithinHorizon(candidate: {
+    nativeEndAt: string | null;
+}, maxEndDays: number | undefined, nowMs: number): boolean;
+/** Dedicated v2 discovery only. Filter and deduplicate before the model cap;
+ * the legacy expansion and legacy agent discovery remain unchanged. */
+export declare function pmPaperCandidates(payload: unknown, held: ReadonlySet<string>, maxEndDays: number | undefined, nowMs: number): (Omit<import("./types.js").PmMarket, "ref"> & {
+    nativeMarketKey: string;
+    nativeEndAt: string | null;
+    nativeEndBasis: "gamma_market_endDate" | "kalshi_market_close_time";
+    settlementTimeKnown: false;
+})[];