@coinrithm/mcp-trading 0.1.8 → 0.3.0

package/dist/agent/cli.js

@@ -0,0 +1,382 @@
+// coinrithm-agent — the public scaffolder/inspector CLI.
+//
+// Authors, validates, ejects, locks, and inspects agent DEFINITIONS. It does
+// NOT trade, call a model, or hit the live API — it only compiles folders into
+// the AgentSpec the resolver produces. Commands return a structured CmdResult
+// so they are unit-testable without spawning a process.
+import { mkdirSync, writeFileSync, existsSync, statSync, readFileSync, openSync, closeSync, unlinkSync, } from "node:fs";
+import { resolve as resolvePath, dirname, join, basename } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { resolveAgent, ResolveError, mergeProseParts, isSkillProseSource } from "./resolve.js";
+import { buildSpec, loadAgent } from "./skill.js";
+import { validateSkill } from "./skillValidator.js";
+import { strictLint } from "./strictLint.js";
+import { checkCapabilityDrift } from "./capabilityGuard.js";
+import { buildManifest, writeManifest } from "./manifest.js";
+import { parseFrontmatter } from "./frontmatter.js";
+import { renderFolderOfOne, ejectFiles, PRESET_NAMES } from "./templates.js";
+import { COINRITHM_API } from "./version.js";
+import { stableStringify, envFlag } from "./util.js";
+import { CoinRithmClient } from "./client.js";
+import { selectProvider } from "./providers.js";
+import { runLoop } from "./runner.js";
+import { loadState, saveState } from "./state.js";
+import { makeRunId } from "./runEvidence.js";
+const fail = (lines) => ({ ok: false, code: 1, lines });
+function issuesResult(issues, header) {
+    return {
+        ok: false,
+        code: 1,
+        lines: [
+            `✗ ${header}`,
+            ...issues.map((i) => `  [${i.code}] ${i.path ? `${i.path}: ` : ""}${i.message}`),
+        ],
+    };
+}
+function agentDirOf(path) {
+    const abs = resolvePath(path);
+    return existsSync(abs) && statSync(abs).isDirectory() ? abs : dirname(abs);
+}
+function pinWarnings(path) {
+    try {
+        const pin = join(agentDirOf(path), "functionality", "coinrithm.yaml");
+        if (!existsSync(pin))
+            return [];
+        const parsed = parseYaml(readFileSync(pin, "utf8"));
+        const v = parsed?.api?.openapiVersion;
+        if (v && v !== COINRITHM_API.openapiVersion) {
+            return [
+                `⚠ functionality/coinrithm.yaml pins API ${v}; current is ${COINRITHM_API.openapiVersion} (warning only, not a block)`,
+            ];
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return [];
+}
+export function cmdNew(targetPath, opts = {}) {
+    const template = opts.template ?? "momentum-futures";
+    if (template !== "momentum-futures") {
+        return fail([`unknown template "${template}" (only: momentum-futures)`]);
+    }
+    const preset = (opts.preset ?? "conservative");
+    if (!PRESET_NAMES.includes(preset)) {
+        return fail([`unknown preset "${preset}" (allowed: ${PRESET_NAMES.join(", ")})`]);
+    }
+    const dir = resolvePath(targetPath);
+    if (!dir || dir === resolvePath("."))
+        return fail(["provide a target directory name"]);
+    if (existsSync(dir))
+        return fail([`refusing to overwrite existing path: ${dir}`]);
+    const name = basename(dir);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "agent.md"), renderFolderOfOne(name, preset), "utf8");
+    return {
+        ok: true,
+        code: 0,
+        lines: [
+            `created ${join(dir, "agent.md")} (template=${template}, preset=${preset})`,
+            `next: coinrithm-agent validate "${dir}"`,
+        ],
+    };
+}
+export function cmdValidate(path, mode = "self-host") {
+    let resolved;
+    try {
+        resolved = resolveAgent(path);
+    }
+    catch (e) {
+        if (e instanceof ResolveError)
+            return issuesResult(e.issues, "resolve failed");
+        throw e;
+    }
+    const raw = resolved.rawFrontmatter;
+    const spec = buildSpec(raw);
+    const lint = [...strictLint(raw), ...checkCapabilityDrift(resolved, spec)];
+    const v = validateSkill({ spec, body: resolved.mergedProse, raw }, mode);
+    const lintFatal = mode === "hosted";
+    const lines = [];
+    for (const i of lint) {
+        lines.push(`${lintFatal ? "✗" : "⚠"} ${i.code}${i.path ? ` (${i.path})` : ""}: ${i.message}`);
+    }
+    for (const i of v.issues)
+        lines.push(`✗ ${i.code}: ${i.reason}`);
+    lines.push(...pinWarnings(path));
+    const ok = v.valid && (!lintFatal || lint.length === 0);
+    lines.unshift(ok ? `✓ valid (${mode})` : `✗ invalid (${mode})`);
+    return { ok, code: ok ? 0 : 1, lines, data: { lint, validation: v } };
+}
+export function cmdLock(path) {
+    const v = cmdValidate(path, "self-host");
+    if (!v.ok)
+        return { ...v, lines: ["refusing to lock an invalid agent:", ...v.lines] };
+    const resolved = resolveAgent(path);
+    const spec = buildSpec(resolved.rawFrontmatter);
+    const manifest = buildManifest(resolved, spec);
+    const out = writeManifest(agentDirOf(path), manifest);
+    // Self-host treats capability drift as advisory (not fatal), but locking past
+    // it silently would hide it — surface it so the author isn't surprised when
+    // `validate --hosted` later rejects the same folder.
+    const drift = (v.data?.lint ?? []).filter((i) => i.code.startsWith("drift_"));
+    const warn = drift.length
+        ? [
+            `⚠ locked with ${drift.length} advisory capability-drift note(s) — \`validate --hosted\` would reject these:`,
+            ...drift.map((i) => `  [${i.code}] ${i.path ? `${i.path}: ` : ""}${i.message}`),
+        ]
+        : [];
+    return { ok: true, code: 0, lines: [`wrote ${out}`, `configHash ${manifest.configHash}`, ...warn] };
+}
+export function cmdEject(path) {
+    const agentDir = agentDirOf(path);
+    const abs = resolvePath(path);
+    const keystone = existsSync(abs) && statSync(abs).isDirectory() ? join(abs, "agent.md") : abs;
+    if (!existsSync(keystone))
+        return fail([`no agent.md at ${keystone}`]);
+    const { data: fm, body } = parseFrontmatter(readFileSync(keystone, "utf8"));
+    if (Array.isArray(fm.extends)) {
+        return fail(["agent already uses `extends` (already ejected?) — nothing to do"]);
+    }
+    const before = buildSpec(fm);
+    const { files } = ejectFiles(fm, body);
+    for (const [rel, content] of Object.entries(files)) {
+        const p = join(agentDir, rel);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, content, "utf8");
+    }
+    let after;
+    try {
+        after = buildSpec(resolveAgent(agentDir).rawFrontmatter);
+    }
+    catch (e) {
+        return fail([`ejected folder failed to re-resolve: ${e.message}`]);
+    }
+    const same = stableStringify(before) === stableStringify(after);
+    const lines = [
+        `ejected into ${agentDir}`,
+        ...Object.keys(files).map((f) => `  + ${f}`),
+        same ? "✓ resolved spec unchanged" : "✗ WARNING: resolved spec CHANGED after eject",
+    ];
+    return { ok: same, code: same ? 0 : 1, lines };
+}
+export function cmdInspect(path, json = false) {
+    let resolved;
+    try {
+        resolved = resolveAgent(path);
+    }
+    catch (e) {
+        if (e instanceof ResolveError)
+            return issuesResult(e.issues, "resolve failed");
+        throw e;
+    }
+    const spec = buildSpec(resolved.rawFrontmatter);
+    const lint = [...strictLint(resolved.rawFrontmatter), ...checkCapabilityDrift(resolved, spec)];
+    const v = validateSkill({ spec, body: resolved.mergedProse, raw: resolved.rawFrontmatter }, "self-host");
+    const output = {
+        resolvedConfig: resolved.rawFrontmatter,
+        provenance: resolved.provenance,
+        contentHashes: resolved.contentHashes,
+        validation: { valid: v.valid, issues: v.issues, lint },
+    };
+    if (json) {
+        return { ok: v.valid, code: 0, lines: [JSON.stringify(output, null, 2)], data: output };
+    }
+    const lines = [
+        `name:        ${spec.name}`,
+        `venues:      ${spec.venues.join(", ")}`,
+        `cadence:     ${spec.trigger.cadence}`,
+        `model:       ${spec.model ? `${spec.model.provider}/${spec.model.name}` : "(host free-tier)"}`,
+        `risk:        maxLeverage=${spec.risk.maxLeverage} perTradeMargin=${spec.risk.perTradeMarginMusd} requireStopLoss=${spec.risk.requireStopLoss}`,
+        `sources:     ${Object.keys(resolved.contentHashes).length} file(s)`,
+        `validation:  ${v.valid ? "valid" : "INVALID"}${lint.length ? ` (+${lint.length} lint note(s))` : ""}`,
+    ];
+    return { ok: v.valid, code: 0, lines, data: output };
+}
+// Acquire an exclusive per-agent run lock (O_EXCL). Returns a release fn, or
+// null if another runner already holds it — so two runners can't race one
+// state file and bypass the daily / write caps.
+function acquireLock(stateFile) {
+    const lock = `${stateFile}.lock`;
+    let fd;
+    try {
+        fd = openSync(lock, "wx");
+    }
+    catch {
+        return null;
+    }
+    try {
+        writeFileSync(fd, JSON.stringify({ pid: process.pid }));
+    }
+    catch {
+        /* best effort */
+    }
+    return () => {
+        try {
+            closeSync(fd);
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            unlinkSync(lock);
+        }
+        catch {
+            /* ignore */
+        }
+    };
+}
+// Run the agent locally (self-host). Dry-run by default; --live (or LIVE=1)
+// places paper trades. Reads COINRITHM_API_KEY + the model key from the ENV.
+export async function cmdRun(path, opts = {}) {
+    let loaded;
+    try {
+        loaded = loadAgent(path, "self-host");
+    }
+    catch (e) {
+        if (e instanceof ResolveError)
+            return issuesResult(e.issues, "resolve failed");
+        throw e;
+    }
+    const apiKey = process.env.COINRITHM_API_KEY;
+    if (!apiKey)
+        return fail(["COINRITHM_API_KEY is not set (needed to read your paper account)"]);
+    let provider;
+    try {
+        provider = selectProvider(loaded.spec, process.env, fetch);
+    }
+    catch (e) {
+        return fail([e.message]);
+    }
+    const client = new CoinRithmClient({ apiKey, baseUrl: process.env.COINRITHM_API_URL });
+    const stateFile = opts.stateFile ?? join(agentDirOf(path), ".agent.state.json");
+    const release = acquireLock(stateFile);
+    if (!release) {
+        return fail([`another runner holds ${stateFile}.lock — only one runner per agent at a time`]);
+    }
+    try {
+        let state;
+        try {
+            state = loadState(stateFile, makeRunId(loaded.spec));
+        }
+        catch (e) {
+            // Corrupt state is fail-closed: refuse to run rather than reset guards.
+            return fail([e.message]);
+        }
+        if (state.disabled) {
+            return fail([`agent is disabled: ${state.disabledReason ?? "kill-switch"} — clear ${stateFile} to reset`]);
+        }
+        const live = !!opts.live;
+        const lines = [
+            `run ${live ? "LIVE (paper trades WILL be placed)" : "DRY-RUN (no writes; set --live or LIVE=1)"} — ${loaded.spec.name}`,
+        ];
+        // Skills ablation kill-switch: drop tactic-skill prose from the prompt for
+        // token-cost control or A/B testing. Affects ONLY the run-time prompt — the
+        // resolver, manifest, and caps are untouched (the spec is still enforced).
+        const disableSkills = envFlag(process.env.COINRITHM_AGENT_DISABLE_SKILLS);
+        const mergedProse = disableSkills
+            ? mergeProseParts(loaded.resolved.proseParts.filter((p) => !isSkillProseSource(p.source)))
+            : loaded.body;
+        if (disableSkills) {
+            const dropped = loaded.resolved.proseParts.filter((p) => isSkillProseSource(p.source)).length;
+            lines.push(`skills DISABLED via COINRITHM_AGENT_DISABLE_SKILLS — ${dropped} tactic skill(s) dropped from the prompt (caps unchanged)`);
+        }
+        const deps = {
+            client,
+            provider,
+            spec: loaded.spec,
+            mergedProse,
+            state,
+            live,
+            stateFile,
+            log: (l) => lines.push(l),
+        };
+        const results = await runLoop(deps, { once: opts.once });
+        saveState(stateFile, state);
+        const wrote = results.some((res) => res.planned.some((p) => p.executed));
+        lines.push(`done: ${results.length} cycle(s)${wrote ? "" : ", no writes"}`);
+        return { ok: true, code: 0, lines, data: results };
+    }
+    finally {
+        release();
+    }
+}
+function parseFlags(args) {
+    const out = { _: [] };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--hosted")
+            out.hosted = true;
+        else if (a === "--self-host")
+            out.hosted = false;
+        else if (a === "--json")
+            out.json = true;
+        else if (a === "--once")
+            out.once = true;
+        else if (a === "--live")
+            out.live = true;
+        else if (a === "--dry-run")
+            out.dryRun = true;
+        else if (a === "--template")
+            out.template = args[++i];
+        else if (a === "--preset")
+            out.preset = args[++i];
+        else if (a === "--state")
+            out.state = args[++i];
+        else
+            out._.push(a);
+    }
+    return out;
+}
+function usageLines() {
+    return [
+        "coinrithm-agent — author + run CoinRithm paper-trading agents (simulated funds only)",
+        "  new <dir> --template momentum-futures --preset conservative|balanced|bold",
+        "  validate <path> [--hosted | --self-host]",
+        "  inspect <path> [--json]",
+        "  eject <agent.md | dir>",
+        "  lock <path>",
+        "  run <path> [--once] [--live] [--dry-run] [--state <file>]   (dry-run by default)",
+    ];
+}
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    const flags = parseFlags(rest);
+    const pos = flags._;
+    let r;
+    switch (cmd) {
+        case "new":
+            r = cmdNew(pos[0] ?? "", { template: flags.template, preset: flags.preset });
+            break;
+        case "validate":
+            r = cmdValidate(pos[0] ?? ".", flags.hosted ? "hosted" : "self-host");
+            break;
+        case "lock":
+            r = cmdLock(pos[0] ?? ".");
+            break;
+        case "eject":
+            r = cmdEject(pos[0] ?? ".");
+            break;
+        case "inspect":
+            r = cmdInspect(pos[0] ?? ".", !!flags.json);
+            break;
+        case "run": {
+            // dry-run is the default; only --live (or LIVE=1) AND not --dry-run trades.
+            const live = (!!flags.live || process.env.LIVE === "1") && !flags.dryRun;
+            r = await cmdRun(pos[0] ?? ".", { once: flags.once, live, stateFile: flags.state });
+            break;
+        }
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            r = { ok: true, code: 0, lines: usageLines() };
+            break;
+        default:
+            r = { ok: false, code: 1, lines: [`unknown command "${cmd}"`, ...usageLines()] };
+    }
+    for (const line of r.lines) {
+        // eslint-disable-next-line no-console
+        console.log(line);
+    }
+    return r.code;
+}

package/dist/agent/client.d.ts

@@ -0,0 +1,107 @@
+import { AgentTrace, ApiResult } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    fetchFn?: typeof fetch;
+    sleepFn?: (ms: number) => Promise<void>;
+    maxRetries?: number;
+}
+export declare class CoinRithmClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchFn;
+    private readonly sleepFn;
+    private readonly maxRetries;
+    rateLimitHits: number;
+    constructor(cfg: ClientConfig);
+    private request;
+    me(trace?: AgentTrace): Promise<ApiResult>;
+    portfolio(trace?: AgentTrace): Promise<ApiResult>;
+    wallet(query?: {
+        coinId?: string;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    resolve(q: string, trace?: AgentTrace): Promise<ApiResult>;
+    market(coinId: string, trace?: AgentTrace): Promise<ApiResult>;
+    candles(coinId: string, range: string, trace?: AgentTrace): Promise<ApiResult>;
+    trades(query?: {
+        venue?: string;
+        limit?: number;
+        updatedSince?: string;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    futuresPositions(query?: {
+        updatedSince?: string;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    futuresQuote(body: {
+        coinId: string;
+        side: string;
+        leverage: number;
+        marginMusd: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    openOrders(query?: {
+        coinId?: string;
+        updatedSince?: string;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    spotQuote(body: {
+        coinId: string;
+        side: string;
+        quantity: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    discoverPmMarkets(query?: {
+        q?: string;
+        source?: string;
+        limit?: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    pmPositions(query?: {
+        updatedSince?: string;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    pmQuote(body: {
+        source: string;
+        slug: string;
+        outcomeExternalMarketId: string;
+        stakeMusd: number;
+    }, trace?: AgentTrace): Promise<ApiResult>;
+    openFutures(body: {
+        coinId: string;
+        side: string;
+        leverage: number;
+        marginMusd: number;
+        idempotencyKey: string;
+        stopLossPrice?: number | null;
+        takeProfitPrice?: number | null;
+        agentTrace?: AgentTrace;
+    }): Promise<ApiResult>;
+    closeFutures(body: {
+        positionId: number;
+        fraction?: number;
+        idempotencyKey: string;
+        agentTrace?: AgentTrace;
+    }): Promise<ApiResult>;
+    setFuturesSlTp(body: {
+        positionId: number;
+        stopLossPrice?: number | null;
+        takeProfitPrice?: number | null;
+        agentTrace?: AgentTrace;
+    }): Promise<ApiResult>;
+    placeSpotOrder(body: {
+        coinId: string;
+        side: string;
+        orderType: string;
+        quantity: number;
+        limitPrice?: number;
+        stopPrice?: number;
+        idempotencyKey: string;
+        agentTrace?: AgentTrace;
+    }): Promise<ApiResult>;
+    cancelSpotOrder(orderId: number, trace?: AgentTrace): Promise<ApiResult>;
+    openPmPosition(body: {
+        source: string;
+        slug: string;
+        outcomeExternalMarketId: string;
+        stakeMusd: number;
+        idempotencyKey: string;
+        agentTrace?: AgentTrace;
+    }): Promise<ApiResult>;
+    exportRunEvidence(runId: string): Promise<ApiResult>;
+}
+export declare function isFailClosed(status: number): boolean;

package/dist/agent/client.js

@@ -0,0 +1,173 @@
+// 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 { sleep as realSleep } from "./util.js";
+export const DEFAULT_BASE_URL = "https://api.coinrithm.com";
+function traceHeaders(trace) {
+    const h = {};
+    if (!trace)
+        return h;
+    if (trace.runId)
+        h["X-CoinRithm-Run-Id"] = trace.runId;
+    if (trace.decisionId)
+        h["X-CoinRithm-Decision-Id"] = trace.decisionId;
+    if (trace.strategyLabel)
+        h["X-CoinRithm-Strategy-Label"] = trace.strategyLabel;
+    if (typeof trace.confidence === "number")
+        h["X-CoinRithm-Confidence"] = String(trace.confidence);
+    return h;
+}
+export class CoinRithmClient {
+    apiKey;
+    baseUrl;
+    fetchFn;
+    sleepFn;
+    maxRetries;
+    // Every 429 seen this session (read or write, retried or not) — feeds the
+    // rate-limit-pressure kill-switch, which a write-only counter would miss.
+    rateLimitHits = 0;
+    constructor(cfg) {
+        this.apiKey = cfg.apiKey;
+        this.baseUrl = (cfg.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.fetchFn = cfg.fetchFn ?? fetch;
+        this.sleepFn = cfg.sleepFn ?? realSleep;
+        this.maxRetries = cfg.maxRetries ?? 3;
+    }
+    async request(method, path, opts = {}) {
+        const url = new URL(this.baseUrl + path);
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null && v !== "")
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            ...traceHeaders(opts.trace),
+        };
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchFn(url.toString(), {
+                    method,
+                    headers,
+                    body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                });
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    status: 0,
+                    data: { error: "network_error", message: err instanceof Error ? err.message : String(err) },
+                };
+            }
+            const retryAfter = Number(res.headers.get("retry-after"));
+            if (res.status === 429)
+                this.rateLimitHits += 1;
+            if (res.status === 429 && attempt < this.maxRetries) {
+                await this.sleepFn((Number.isFinite(retryAfter) ? retryAfter : 5) * 1000);
+                continue;
+            }
+            const text = await res.text();
+            let data = text;
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    /* leave as text */
+                }
+            }
+            return {
+                ok: res.ok,
+                status: res.status,
+                data,
+                retryAfterSeconds: res.status === 429 && Number.isFinite(retryAfter) ? retryAfter : undefined,
+                rateLimitRemaining: Number(res.headers.get("ratelimit-remaining")) || undefined,
+                ledgerEventId: res.headers.get("x-coinrithm-ledger-event-id"),
+            };
+        }
+    }
+    // ── reads ──────────────────────────────────────────────────────────────────
+    me(trace) {
+        return this.request("GET", "/api/agent/me", { trace });
+    }
+    portfolio(trace) {
+        return this.request("GET", "/api/agent/portfolio", { trace });
+    }
+    wallet(query, trace) {
+        return this.request("GET", "/api/agent/wallet", { query, trace });
+    }
+    resolve(q, trace) {
+        return this.request("GET", "/api/agent/resolve", { query: { q }, trace });
+    }
+    market(coinId, trace) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}`, { trace });
+    }
+    candles(coinId, range, trace) {
+        return this.request("GET", `/api/agent/market/${encodeURIComponent(coinId)}/candles`, {
+            query: { range },
+            trace,
+        });
+    }
+    trades(query, trace) {
+        return this.request("GET", "/api/agent/trades", { query, trace });
+    }
+    futuresPositions(query, trace) {
+        return this.request("GET", "/api/agent/positions/futures", { query, trace });
+    }
+    futuresQuote(body, trace) {
+        return this.request("POST", "/api/agent/futures/quote", { body: { ...body, agentTrace: trace } });
+    }
+    // ── spot ─────────────────────────────────────────────────────────────────
+    openOrders(query, trace) {
+        return this.request("GET", "/api/agent/orders/open", { query, trace });
+    }
+    spotQuote(body, trace) {
+        return this.request("POST", "/api/agent/spot/quote", { body: { ...body, agentTrace: trace } });
+    }
+    // ── prediction markets ───────────────────────────────────────────────────
+    discoverPmMarkets(query, trace) {
+        return this.request("GET", "/api/agent/pm/discover", { query, trace });
+    }
+    pmPositions(query, trace) {
+        return this.request("GET", "/api/agent/positions/pm", { query, trace });
+    }
+    pmQuote(body, trace) {
+        return this.request("POST", "/api/agent/pm/quote", { body: { ...body, agentTrace: trace } });
+    }
+    // ── writes ─────────────────────────────────────────────────────────────────
+    openFutures(body) {
+        return this.request("POST", "/api/agent/futures/open", { body });
+    }
+    closeFutures(body) {
+        return this.request("POST", "/api/agent/futures/close", { body });
+    }
+    setFuturesSlTp(body) {
+        return this.request("POST", "/api/agent/futures/sl-tp", { body });
+    }
+    placeSpotOrder(body) {
+        return this.request("POST", "/api/agent/spot/order", { body });
+    }
+    cancelSpotOrder(orderId, trace) {
+        return this.request("POST", `/api/agent/spot/order/${orderId}/cancel`, { trace });
+    }
+    openPmPosition(body) {
+        return this.request("POST", "/api/agent/pm/open", { body });
+    }
+    // Run-evidence export — runId is URL-encoded into the query.
+    exportRunEvidence(runId) {
+        return this.request("GET", "/api/agent/ledger/export", { query: { runId } });
+    }
+}
+// 401/403/409/422 are terminal, fail-closed outcomes for a cycle (auth/scope,
+// conflict, or a risk-gate rejection) — never retried as if transient.
+export function isFailClosed(status) {
+    return status === 401 || status === 403 || status === 409 || status === 422;
+}