@coinrithm/mcp-trading 0.7.7 → 0.7.9

package/dist/agent/types.d.ts

@@ -1,4 +1,5 @@
 import { IndicatorSet } from "./indicators.js";
+import type { DecisionInputRecord } from "./decisionReceipt.js";
 export declare const SPEC_VERSION = "coinrithm.agent.v1";
 export type Venue = "spot" | "futures" | "pm";
 export declare const VENUES: readonly Venue[];
@@ -39,6 +40,38 @@ export interface LimitsConfig {
     maxDailyLossMusd: number;
     maxOpenMarginMusd: number;
 }
+/** Opt-in paper experiment. Percent fields are percentage POINTS, not fractions. */
+export interface CapitalSizingPolicy {
+    version: "equity_fraction_v1";
+    futuresRiskPct: number;
+    pmMaxLossPct: number;
+    perTicketCapitalPct: number;
+    totalCapitalPct: number;
+    cashReservePct: number;
+    minRewardRisk: number;
+}
+export type CapitalBook = {
+    status: "unavailable";
+    reason: string;
+} | {
+    status: "ready";
+    walletId: number;
+    /** Marked spot + collateral, reduced by known negative position marks.
+     * Positive open-position gains are excluded; this is NOT complete MTM. */
+    conservativeEquityMusd: number;
+    cashAvailableMusd: number;
+    committedCapitalMusd: number;
+};
+export interface CapitalSizingAdjustment {
+    version: "equity_fraction_v1";
+    basis: "owned_collateral_spot_marked_negative_position_marks_only";
+    proposedAmountMusd?: number;
+    sizedAmountMusd?: number;
+    conservativeEquityMusd?: number;
+    riskBudgetMusd?: number;
+    /** Runner safety estimate, not a claim that the venue charges this fee. */
+    feeBufferBps?: number;
+}
 export interface AbstentionConfig {
     onStaleData: boolean;
     onWeakSignal: boolean;
@@ -72,6 +105,7 @@ export interface AgentSpec {
     model?: ModelConfig;
     venues: Venue[];
     risk: RiskConfig;
+    capitalSizing?: CapitalSizingPolicy;
     limits: LimitsConfig;
     abstention: AbstentionConfig;
     sync: SyncConfig;
@@ -95,6 +129,8 @@ export declare const fail: (code: string, reason: string) => ValidationResult;
 export interface Freshness {
     status: string;
     ageSeconds?: number;
+    asOf?: string;
+    basis?: string;
 }
 export interface WatchEntry {
     symbol: string;
@@ -108,10 +144,25 @@ export interface WatchEntry {
     freshness?: Freshness;
     indicators?: IndicatorSet;
     discovered?: boolean;
+    slug?: string;
+    fundamentals?: CoinFundamentals;
+}
+export interface CoinFundamentals {
+    categories?: string[];
+    marketCapRank?: number;
+    marketCapUsd?: number;
+    volume24hUsd?: number;
+    headlines?: Array<{
+        title: string;
+        at?: string;
+        importance?: number;
+        sentiment?: string;
+    }>;
 }
 export interface OpenPosition {
     venue: Venue;
     id: number;
+    walletId?: number;
     coinId?: string;
     symbol?: string;
     side?: string;
@@ -124,6 +175,8 @@ export interface OpenPosition {
     liquidationPrice?: number;
     stopLossPrice?: number;
     takeProfitPrice?: number;
+    openedAt?: string;
+    thesis?: ThesisView;
 }
 export interface SpotOrder {
     id: number;
@@ -136,12 +189,19 @@ export interface SpotOrder {
 }
 export interface PmPosition {
     id: number;
+    walletId?: number;
     source?: string;
     slug?: string;
     outcomeExternalMarketId?: string;
     stakeMusd?: number;
     unrealizedPnlMusd?: number;
     status?: string;
+    title?: string;
+    side?: string;
+    entryProbability?: number;
+    currentProbability?: number;
+    openedAt?: string;
+    thesis?: ThesisView;
 }
 export interface PmResolution {
     id: number;
@@ -162,6 +222,27 @@ export interface PmMarket {
     title?: string;
     freshness?: Freshness;
     volumeUsd?: number;
+    endDate?: string;
+    liquidityUsd?: number;
+    quality?: PmQuality;
+    decisionSupport?: PmDecisionSupport;
+}
+export interface PmQuality {
+    decisionEligible?: boolean;
+    warningReasons: string[];
+    blockReasons: string[];
+    policyVersion?: string;
+    assessedAt?: string;
+    reasonsOmitted?: boolean;
+}
+export interface PmDecisionSupport {
+    qualityScore?: number;
+    qualityTier?: string;
+    qualityCapReason?: string | null;
+    spreadTier?: string;
+    liquidityTier?: string;
+    volumeTier?: string;
+    flags?: Partial<Record<"thinMarket" | "inactiveMarket" | "highAmbiguity" | "nearResolution" | "staleData", boolean>>;
 }
 export interface SetupSignal {
     symbol: string;
@@ -177,6 +258,7 @@ export interface NewsItem {
     sentiment?: string;
     importance?: number;
     ageHours?: number;
+    publishedAt?: string;
     coins?: string[];
 }
 export interface Observation {
@@ -184,6 +266,7 @@ export interface Observation {
     scopes: string[];
     cashAvailableMusd: number | null;
     equityMusd: number | null;
+    capitalBook?: CapitalBook;
     openPositions: OpenPosition[];
     openOrders: SpotOrder[];
     pmPositions: PmPosition[];
@@ -206,6 +289,35 @@ export interface Observation {
         priceUsd?: number;
     }>;
 }
+export interface ThesisInvalidation {
+    priceBelow?: number;
+    priceAbove?: number;
+    probabilityBelow?: number;
+    probabilityAbove?: number;
+    maxHoldMinutes?: number;
+    catalyst?: string;
+}
+export interface Thesis {
+    summary: string;
+    invalidation: ThesisInvalidation;
+}
+export interface PositionThesis extends Thesis {
+    venue: Venue;
+    positionId: number;
+    symbol?: string;
+    side?: string;
+    source?: string;
+    slug?: string;
+    outcomeExternalMarketId?: string;
+    openedAt: string;
+    entryPrice?: number;
+    entryProbability?: number;
+}
+export interface ThesisView extends Thesis {
+    holdMinutes: number;
+    status: "intact" | "invalidated";
+    invalidatedBy?: string;
+}
 export type ProposedAction = {
     type: "futures_open";
     symbol: string;
@@ -216,6 +328,7 @@ export type ProposedAction = {
     takeProfitPrice?: number | null;
     confidence?: number;
     rationaleSummary?: string;
+    thesis?: Thesis;
 } | {
     type: "futures_close";
     positionId: number;
@@ -237,6 +350,7 @@ export type ProposedAction = {
     stopPrice?: number;
     confidence?: number;
     rationaleSummary?: string;
+    thesis?: Thesis;
 } | {
     type: "spot_cancel";
     orderId: number;
@@ -250,6 +364,7 @@ export type ProposedAction = {
     confidence?: number;
     rationaleSummary?: string;
     forecastProbability?: number;
+    thesis?: Thesis;
 };
 export type ActionVenue = Venue;
 export declare function actionVenue(a: ProposedAction): ActionVenue;
@@ -273,7 +388,14 @@ export interface QuoteEvidence {
     entryPrice?: number;
     liquidationPrice?: number;
     executionPrice?: number;
+    entryProbability?: number;
+    stakeMusd?: number;
+    sharesEstimate?: number;
     estimatedCostMusd?: number;
+    estimatedFeeMusd?: number;
+    futuresFeeBps?: number;
+    estimatedEntryFeeMusd?: number;
+    cashRequiredMusd?: number;
     freshness?: Freshness;
     openBlocked?: boolean;
     openBlockReasons?: unknown;
@@ -282,6 +404,7 @@ export interface RunState {
     runId: string;
     cyclesRun: number;
     writesToday: number;
+    riskIncreasesToday: number;
     realizedPnlMusd: number;
     peakRealizedMusd: number;
     consecutiveRejectCycles: number;
@@ -304,6 +427,7 @@ export interface RunState {
         at: string;
         did: string;
     }>;
+    theses?: Record<string, PositionThesis>;
 }
 export interface AgentTrace {
     runId?: string;
@@ -330,8 +454,11 @@ export interface PlannedAction {
     quote?: QuoteEvidence;
     executed?: boolean;
     result?: unknown;
+    capitalSizing?: CapitalSizingAdjustment;
 }
 export interface CycleResult {
+    /** Private non-enumerable evidence. Never forward through AgentTrace/public APIs. */
+    decisionInputRecord?: DecisionInputRecord;
     decision: "skip" | "act";
     skipReason?: string;
     rationale?: string;

package/dist/client.js

@@ -17,6 +17,7 @@
 //
 // IMPORTANT: this module must NEVER write to stdout (stdout is the MCP JSON-RPC
 // channel). All diagnostics go to stderr via the logger below.
+import { retryAfterSeconds } from "./retryAfter.js";
 export const DEFAULT_BASE_URL = "https://api.coinrithm.com";
 export function log(...args) {
     // stderr only — stdout is reserved for the MCP protocol.
@@ -139,12 +140,12 @@ export class CoinRithmClient {
         if (res.status === 429) {
             // Surface the back-off contract so an agent can pace itself instead of
             // hammering: 120 req/min per key baseline, 20 trade-writes/min.
-            const retryAfter = Number(res.headers.get("retry-after"));
+            const retryAfter = retryAfterSeconds(res.headers.get("retry-after"));
             data = {
                 ...(typeof data === "object" && data !== null
                     ? data
                     : { error: String(data) }),
-                retryAfterSeconds: Number.isFinite(retryAfter) ? retryAfter : null,
+                retryAfterSeconds: retryAfter ?? null,
                 hint: "Rate limited. Wait retryAfterSeconds (or the Retry-After header) before retrying; pace future calls using the RateLimit-Remaining response header.",
             };
         }

package/dist/http.d.ts

@@ -1,2 +1,8 @@
 #!/usr/bin/env node
-export {};
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CoinRithmClient } from "./client.js";
+import { type CompletionLogger } from "./httpCompletion.js";
+export declare function createHttpApp(client: CoinRithmClient, options?: {
+    completionLogger?: CompletionLogger;
+    createServer?: () => McpServer;
+}): import("express-serve-static-core").Express;

package/dist/http.js

@@ -24,8 +24,8 @@
 //     forwards as `extra.authInfo`, giving requestKey() a second source. Either
 //     way the caller's own key — and only that key — is used for their tool call.
 //   - Unauthenticated MCP initialization and tool-list introspection are allowed
-//     so registries can verify the server. Actual tool calls without a key return
-//     a structured 401 from CoinRithmClient before any upstream request is made.
+//     so registries can verify the server. Public data tools are also keyless;
+//     protected tools return a structured 401 when their key is missing.
 //
 // Config (env):
 //   COINRITHM_API_URL  (optional)  upstream base URL (default production).
@@ -35,15 +35,23 @@
 // the correct isolation model for a multi-user, per-request-keyed surface — no
 // session state is shared between users.
 import express from "express";
+import { pathToFileURL } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CoinRithmClient, bearerFromHeader, loadHttpConfig, log, } from "./client.js";
 import { registerTools } from "./tools.js";
 import { SERVER_VERSION } from "./version.js";
-async function main() {
-    const config = loadHttpConfig(); // no global key — keys arrive per request
-    const client = new CoinRithmClient(config); // constructed WITHOUT a default key
+import { observeHttpCompletion, } from "./httpCompletion.js";
+// Factory permits isolated localhost SDK tests without opening a listener on import.
+export function createHttpApp(client, options = {}) {
     const app = express();
+    const completions = new WeakMap();
+    app.use((req, res, next) => {
+        if (req.method === "POST" && /^\/mcp\/?$/i.test(req.path)) {
+            completions.set(res, observeHttpCompletion(req, res, options.completionLogger));
+        }
+        next();
+    });
     app.use(express.json());
     // Lightweight, unauthenticated liveness probe (handy for Coolify/uptime checks).
     // Keep `/healthz` as the deployment contract and expose `/health` as a
@@ -110,8 +118,8 @@ async function main() {
         // Per-request auth: read THIS caller's key from the Authorization header,
         // or from Smithery's non-reserved forwarding header.
         // It is optional at the transport layer so registries can initialize the
-        // server and list tool schemas. Tool handlers still require a key and return
-        // a structured 401 if one is missing.
+        // server and list tool schemas. Public data tools are keyless; protected
+        // tool handlers return a structured 401 if their key is missing.
         const apiKey = bearerFromHeader(req.headers.authorization) ??
             bearerFromHeader(req.headers["x-coinrithm-api-key"]);
         // Belt-and-suspenders: also expose the token via the SDK's authInfo channel.
@@ -120,11 +128,13 @@ async function main() {
         if (apiKey) {
             req.auth = { token: apiKey, clientId: "coinrithm-key", scopes: [] };
         }
-        const server = new McpServer({
-            name: "coinrithm-trading",
-            version: SERVER_VERSION,
-        });
-        registerTools(server, client);
+        const server = options.createServer?.() ??
+            new McpServer({
+                name: "coinrithm-trading",
+                version: SERVER_VERSION,
+            });
+        if (!options.createServer)
+            registerTools(server, client);
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined, // stateless: no cross-request/user state
         });
@@ -134,6 +144,7 @@ async function main() {
         });
         try {
             await server.connect(transport);
+            completions.get(res)?.attach(transport);
             // The transport reads req.headers (→ extra.requestInfo) and req.auth
             // (→ extra.authInfo); tools.ts picks up the caller's key from there.
             await transport.handleRequest(req, res, req.body);
@@ -149,13 +160,22 @@ async function main() {
             }
         }
     });
+    return app;
+}
+async function main() {
+    const config = loadHttpConfig(); // no global key — keys arrive per request
+    const client = new CoinRithmClient(config); // constructed WITHOUT a default key
+    const app = createHttpApp(client);
     const port = Number(process.env.PORT) || 8787;
     app.listen(port, () => {
         log(`HTTP MCP listening on :${port}/mcp (multi-user, per-request key). ` +
             `upstream=${config.baseUrl}. Paper only.`);
     });
 }
-main().catch((err) => {
-    log("fatal:", err instanceof Error ? err.message : err);
-    process.exit(1);
-});
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        log("fatal:", err instanceof Error ? err.message : err);
+        process.exit(1);
+    });
+}

package/dist/httpCompletion.d.ts

@@ -0,0 +1,33 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+export declare const COMPLETION_TOOL_NAMES: readonly ["whoami", "get_portfolio", "get_wallet", "list_open_orders", "get_positions", "resolve_symbol", "get_equity_curve", "get_my_trades", "get_market_context", "get_candles", "discover_pm_markets", "get_performance", "get_agent_ledger", "export_agent_ledger", "export_run_evidence", "get_arena_leaderboard", "get_arena_agent", "futures_quote", "pm_quote", "spot_quote", "place_spot_order", "cancel_spot_order", "open_futures_position", "set_futures_sl_tp", "close_futures_position", "open_pm_position", "report_pm_opportunity", "pm_data_overview", "pm_data_sources", "pm_data_sources_health", "pm_data_events", "pm_data_event", "pm_data_whales", "pm_data_disagreements", "pm_data_calibration", "pm_data_canonical", "pm_data_volume_history", "get_crypto_movers"];
+type Operation = "initialize" | "tools_list" | "tools_call" | "notification" | "other" | "invalid";
+type Outcome = "result" | "tool_error" | "protocol_error" | "no_response" | "not_applicable";
+type ToolName = (typeof COMPLETION_TOOL_NAMES)[number] | "unknown" | null;
+type RpcCompletion = {
+    operation: Operation;
+    tool: ToolName;
+    rpc_outcome: Outcome;
+    result_http_status: number | null;
+    result_ok: boolean | null;
+};
+export type HttpCompletionRecord = Readonly<RpcCompletion & {
+    event: "mcp_completion";
+    schema_version: 1;
+    completed_at: string;
+    duration_ms: number;
+    service_version: string;
+    transport: "streamable_http";
+    credential_supplied: boolean;
+    http_status: number | null;
+    delivery: "finished" | "aborted";
+}>;
+export type CompletionLogger = (line: string) => void;
+/** Attach before JSON parsing; malformed/rejected HTTP requests remain invalid,
+ * no_response, with their actual HTTP status. Do not read bodies or raw errors.
+ * Authentication and caller origin are deliberately NOT inferred from headers.
+ */
+export declare function observeHttpCompletion(req: IncomingMessage, res: ServerResponse, logger?: CompletionLogger): {
+    attach: (transport: Transport) => void;
+};
+export {};

package/dist/httpCompletion.js

@@ -0,0 +1,220 @@
+import { bearerFromHeader, log } from "./client.js";
+import { SERVER_VERSION } from "./version.js";
+// Explicit, server-owned dimensions; tests compare this with actual tools/list.
+// Never retain a caller's unknown tool name, even truncated or hashed.
+export const COMPLETION_TOOL_NAMES = [
+    "whoami",
+    "get_portfolio",
+    "get_wallet",
+    "list_open_orders",
+    "get_positions",
+    "resolve_symbol",
+    "get_equity_curve",
+    "get_my_trades",
+    "get_market_context",
+    "get_candles",
+    "discover_pm_markets",
+    "get_performance",
+    "get_agent_ledger",
+    "export_agent_ledger",
+    "export_run_evidence",
+    "get_arena_leaderboard",
+    "get_arena_agent",
+    "futures_quote",
+    "pm_quote",
+    "spot_quote",
+    "place_spot_order",
+    "cancel_spot_order",
+    "open_futures_position",
+    "set_futures_sl_tp",
+    "close_futures_position",
+    "open_pm_position",
+    "report_pm_opportunity",
+    "pm_data_overview",
+    "pm_data_sources",
+    "pm_data_sources_health",
+    "pm_data_events",
+    "pm_data_event",
+    "pm_data_whales",
+    "pm_data_disagreements",
+    "pm_data_calibration",
+    "pm_data_canonical",
+    "pm_data_volume_history",
+    "get_crypto_movers",
+];
+const toolNames = new Set(COMPLETION_TOOL_NAMES);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : undefined;
+const status = (value) => typeof value === "number" &&
+    Number.isInteger(value) &&
+    (value === 0 || (value >= 100 && value <= 599))
+    ? value
+    : null;
+const empty = (operation = "invalid", tool = null) => ({
+    operation,
+    tool,
+    rpc_outcome: "no_response",
+    result_http_status: null,
+    result_ok: null,
+});
+/** Attach before JSON parsing; malformed/rejected HTTP requests remain invalid,
+ * no_response, with their actual HTTP status. Do not read bodies or raw errors.
+ * Authentication and caller origin are deliberately NOT inferred from headers.
+ */
+export function observeHttpCompletion(req, res, logger = (line) => log(line)) {
+    const started = performance.now();
+    const credentialSupplied = Boolean(bearerFromHeader(req.headers.authorization) ??
+        bearerFromHeader(req.headers["x-coinrithm-api-key"]));
+    const records = [];
+    // IDs are transient correlations only, never copied into records/logs. Clear
+    // on completion so a late tool callback cannot retain IDs or emit twice.
+    const pending = new Map();
+    let completed = false;
+    let delivery;
+    let sendsInFlight = 0;
+    const emit = () => {
+        if (completed || !delivery || (delivery === "finished" && sendsInFlight))
+            return;
+        completed = true;
+        res.off("finish", onFinish);
+        res.off("close", onClose);
+        res.off("error", onAbort);
+        const elapsed = performance.now() - started;
+        const duration = Number.isFinite(elapsed)
+            ? Math.max(0, Math.round(elapsed * 1000) / 1000)
+            : 0;
+        const completedAt = new Date().toISOString();
+        // A pre-header disconnect has no HTTP status; Node's default 200 is not one.
+        const httpStatus = res.headersSent ? status(res.statusCode) : null;
+        const snapshots = records.length ? records : [empty()];
+        for (const rpc of snapshots) {
+            const record = {
+                event: "mcp_completion",
+                schema_version: 1,
+                completed_at: completedAt,
+                duration_ms: duration,
+                service_version: SERVER_VERSION,
+                transport: "streamable_http",
+                ...rpc,
+                credential_supplied: credentialSupplied,
+                http_status: httpStatus,
+                delivery,
+            };
+            try {
+                logger(JSON.stringify(record));
+            }
+            catch {
+                // Observability must never change a tool response or recurse into logging.
+            }
+        }
+        records.length = 0;
+        pending.clear();
+    };
+    const onFinish = () => {
+        delivery = "finished";
+        emit();
+    };
+    const onAbort = () => {
+        delivery = "aborted";
+        // A computed response in an interrupted stream is not confirmed delivered.
+        // In particular, a still-pending send may reject after this close event.
+        for (const rpc of records) {
+            if (rpc.rpc_outcome !== "not_applicable") {
+                rpc.rpc_outcome = "no_response";
+                rpc.result_http_status = null;
+                rpc.result_ok = null;
+            }
+        }
+        emit();
+    };
+    const onClose = () => {
+        if (!res.writableFinished)
+            onAbort();
+        else
+            onFinish();
+    };
+    res.once("finish", onFinish);
+    res.once("close", onClose);
+    res.once("error", onAbort);
+    const incoming = (message) => {
+        if (completed)
+            return;
+        if (!("method" in message)) {
+            records.push({ ...empty("other"), rpc_outcome: "not_applicable" });
+            return;
+        }
+        if (!("id" in message)) {
+            records.push({ ...empty("notification"), rpc_outcome: "not_applicable" });
+            return;
+        }
+        const operation = message.method === "initialize"
+            ? "initialize"
+            : message.method === "tools/list"
+                ? "tools_list"
+                : message.method === "tools/call"
+                    ? "tools_call"
+                    : "other";
+        const name = operation === "tools_call" ? object(message.params)?.name : undefined;
+        const tool = operation !== "tools_call"
+            ? null
+            : typeof name === "string" && toolNames.has(name)
+                ? name
+                : "unknown";
+        const rpc = empty(operation, tool);
+        records.push(rpc);
+        pending.set(message.id, [...(pending.get(message.id) ?? []), rpc]);
+    };
+    return {
+        attach(transport) {
+            // Call AFTER server.connect (which installs SDK callbacks), before handling
+            // this request. Observe only SDK-accepted messages, not unvalidated bodies.
+            const onmessage = transport.onmessage;
+            transport.onmessage = (message, extra) => {
+                incoming(message);
+                onmessage?.(message, extra);
+            };
+            const send = transport.send.bind(transport);
+            transport.send = async (message, options) => {
+                const matches = "id" in message ? pending.get(message.id) : undefined;
+                // Duplicate IDs are ambiguous; never attribute one response twice.
+                const rpc = !completed && matches?.length === 1 ? matches[0] : undefined;
+                if (!rpc || (!("result" in message) && !("error" in message))) {
+                    return send(message, options);
+                }
+                // This is the SDK's FINAL result, after input/output schema validation.
+                rpc.result_http_status = null;
+                rpc.result_ok = null;
+                if ("error" in message)
+                    rpc.rpc_outcome = "protocol_error";
+                else {
+                    const result = object(message.result);
+                    const structured = object(result?.structuredContent);
+                    rpc.rpc_outcome =
+                        rpc.operation === "tools_call" && result?.isError === true
+                            ? "tool_error"
+                            : "result";
+                    if (rpc.operation === "tools_call") {
+                        rpc.result_http_status = status(structured?.httpStatus);
+                        rpc.result_ok =
+                            typeof structured?.ok === "boolean" ? structured.ok : null;
+                    }
+                }
+                sendsInFlight += 1;
+                try {
+                    return await send(message, options);
+                }
+                catch (error) {
+                    rpc.rpc_outcome = "no_response";
+                    rpc.result_http_status = null;
+                    rpc.result_ok = null;
+                    throw error;
+                }
+                finally {
+                    sendsInFlight -= 1;
+                    emit();
+                }
+            };
+        },
+    };
+}

package/dist/retryAfter.d.ts

@@ -0,0 +1 @@
+export declare function retryAfterSeconds(value: string | null, now?: number): number | undefined;

package/dist/retryAfter.js

@@ -0,0 +1,16 @@
+// Retry-After permits a delay in seconds or an HTTP date. Missing/invalid
+// evidence stays absent, so each caller can apply its explicit fallback.
+export function retryAfterSeconds(value, now = Date.now()) {
+    const raw = value?.trim();
+    if (!raw)
+        return undefined;
+    if (/^\d+(?:\.\d+)?$/.test(raw)) {
+        const seconds = Number(raw);
+        return Number.isFinite(seconds) ? seconds : undefined;
+    }
+    // Avoid Date.parse treating malformed numeric delays (e.g. "-1") as dates.
+    if (!/^[A-Za-z]{3}(?:,|day,|\s)/.test(raw))
+        return undefined;
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, (date - now) / 1000) : undefined;
+}