@coinrithm/mcp-trading 0.1.8 → 0.2.0

package/README.md

@@ -1,7 +1,12 @@
 # @coinrithm/mcp-trading
 
-An MCP server that lets an AI agent paper-trade on CoinRithm (spot, futures,
-prediction markets) using a personal API key.
+CoinRithm paper-trading toolkit. Two binaries:
+
+- **`coinrithm-mcp`** — an MCP server that lets an AI agent paper-trade on
+  CoinRithm (spot, futures, prediction markets) using a personal API key.
+- **`coinrithm-agent`** — a self-host **agent runner**: author an agent as a
+  folder and run an observe→decide→validate→act loop with your own model key
+  (paper, futures v1). See [Agent runner](#agent-runner-coinrithm-agent) below.
 
 > **Paper trading only** — virtual funds (50,000 mUSD). Not financial advice.
 
@@ -12,6 +17,25 @@ npm install
 npm run build
 ```
 
+## Agent runner (`coinrithm-agent`)
+
+This package also ships a **self-host agent runner**. You write an agent as a
+folder (strategy + hard caps in markdown/YAML); the runner compiles it and runs
+an `observe → decide → validate → act` loop, asking *your* model (bring-your-own
+key) for structured decisions and executing only the ones that pass your caps —
+**dry-run by default**, paper-only, futures in v1.
+
+```bash
+coinrithm-agent new my-agent --preset conservative
+coinrithm-agent validate my-agent
+COINRITHM_API_KEY=crk_live_… ANTHROPIC_API_KEY=sk-ant-… \
+  coinrithm-agent run my-agent --once --dry-run
+```
+
+Full guide (env vars, fail-closed guarantees, folder layout):
+**[docs/agent-runner.md](../../docs/agent-runner.md)**. The CoinRithm hosted
+scheduler runs this same engine for you (later).
+
 ## Two ways to run
 
 | Mode | Entry | Auth | Who it's for |
@@ -59,11 +83,11 @@ key upstream. See [`DEPLOY.md`](./DEPLOY.md).
 | `get_market_context` (coinId) | read | `GET /api/agent/market/:coinId` |
 | `get_candles` (coinId, range) | read | `GET /api/agent/market/:coinId/candles` |
 | `discover_pm_markets` | read | `GET /api/agent/pm/discover` |
-| `get_performance` | read | `GET /api/agent/performance` |
-| `get_agent_ledger` | read | `GET /api/agent/ledger` |
-| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
-| `export_run_evidence` | read | `GET /api/agent/ledger/export?runId=...` |
-| `get_arena_leaderboard` | read | `GET /api/arena` |
+| `get_performance` | read | `GET /api/agent/performance` |
+| `get_agent_ledger` | read | `GET /api/agent/ledger` |
+| `export_agent_ledger` | read | `GET /api/agent/ledger/export` |
+| `export_run_evidence` | read | `GET /api/agent/ledger/export?runId=...` |
+| `get_arena_leaderboard` | read | `GET /api/arena` |
 | `get_arena_agent` (handle) | read | `GET /api/arena/:handle` |
 | `list_open_orders` | read | `GET /api/agent/orders/open` |
 | `get_positions` (venue) | read | `GET /api/agent/positions/{futures,pm}` |
@@ -125,18 +149,18 @@ account only, latest stored market/probability snapshots, no explicit
 commission/slippage in v1, no futures funding/fees, and worker-driven resting
 order / SL / TP / settlement timing. It is a reproducibility artifact for your
 run; it is not a full point-in-time market archive and does not expose hidden
-reasoning. Aggregate audit stats include trace coverage for `runId` and
-`decisionId`. Run exports also include `retentionPolicy`: private ledger rows
-use a rolling retention window and exports are capped. They include
-`evidenceChecklist`, a derived pass/warn/fail checklist for trace completeness,
-decision ids, quote-before-trade coverage, rejected calls, export truncation,
-execution assumptions, and outcome attribution; it does not create additional
-retained data. `outcomeSummary` derives best-effort realized PnL from existing
-related trade/position ids, and spot orders can also match through their
-idempotency keys once a terminal `ClosedOrder` exists. It reports whether
-coverage is `none`, `partial`, or `complete`; it does not store new data. Public
-Arena surfaces only aggregate audit stats; raw request logs and rationale
-summaries stay private.
+reasoning. Aggregate audit stats include trace coverage for `runId` and
+`decisionId`. Run exports also include `retentionPolicy`: private ledger rows
+use a rolling retention window and exports are capped. They include
+`evidenceChecklist`, a derived pass/warn/fail checklist for trace completeness,
+decision ids, quote-before-trade coverage, rejected calls, export truncation,
+execution assumptions, and outcome attribution; it does not create additional
+retained data. `outcomeSummary` derives best-effort realized PnL from existing
+related trade/position ids, and spot orders can also match through their
+idempotency keys once a terminal `ClosedOrder` exists. It reports whether
+coverage is `none`, `partial`, or `complete`; it does not store new data. Public
+Arena surfaces only aggregate audit stats; raw request logs and rationale
+summaries stay private.
 
 `get_my_trades`, `list_open_orders`, and `get_positions` accept an optional
 `updatedSince` cursor and their responses carry `asOf` — pass it back to poll

package/dist/agent/act.js

@@ -0,0 +1,65 @@
+// Act phase: fetch the quote evidence for an open (the runner does this, never
+// the model) and execute a validated futures action with an idempotency key.
+import { asObj, asNum, asStr } from "./extract.js";
+function coinIdFor(observation, symbol) {
+    return observation.watch.find((w) => w.symbol.toUpperCase() === symbol.toUpperCase())?.coinId ?? undefined;
+}
+function freshnessOf(block) {
+    const fr = asObj(block.freshness);
+    const status = asStr(fr.status);
+    return status ? { status, ageSeconds: asNum(fr.ageSeconds) } : undefined;
+}
+// Read-only quote BEFORE any open. Returns ineligible (never throws) on error.
+export async function fetchQuote(client, action, observation, trace) {
+    if (action.type !== "futures_open")
+        return undefined;
+    const coinId = coinIdFor(observation, action.symbol);
+    if (!coinId)
+        return { eligible: false, blockReasons: ["unresolved_symbol"] };
+    const r = await client.futuresQuote({ coinId, side: action.side, leverage: action.leverage, marginMusd: action.marginMusd }, trace);
+    if (!r.ok)
+        return { eligible: false, blockReasons: [`quote_http_${r.status}`] };
+    const d = asObj(r.data);
+    return {
+        eligible: d.eligible === true,
+        blockReasons: d.blockReasons,
+        entryPrice: asNum(d.entryPrice),
+        liquidationPrice: asNum(d.liquidationPrice),
+        // Freshness lives in the response's `observation` block (anti-look-ahead).
+        freshness: freshnessOf(asObj(d.observation)),
+    };
+}
+export async function executeAction(client, action, observation, trace, idempotencyKey) {
+    if (action.type === "futures_open") {
+        const coinId = coinIdFor(observation, action.symbol);
+        if (!coinId)
+            return { ok: false, status: 0, data: { error: "unresolved_symbol" } };
+        return client.openFutures({
+            coinId,
+            side: action.side,
+            leverage: action.leverage,
+            marginMusd: action.marginMusd,
+            idempotencyKey,
+            stopLossPrice: action.stopLossPrice ?? null,
+            takeProfitPrice: action.takeProfitPrice ?? null,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "futures_close") {
+        return client.closeFutures({
+            positionId: action.positionId,
+            fraction: action.fraction,
+            idempotencyKey,
+            agentTrace: trace,
+        });
+    }
+    if (action.type === "futures_set_sltp") {
+        return client.setFuturesSlTp({
+            positionId: action.positionId,
+            stopLossPrice: action.stopLossPrice ?? undefined,
+            takeProfitPrice: action.takeProfitPrice ?? undefined,
+            agentTrace: trace,
+        });
+    }
+    return { ok: false, status: 0, data: { error: "unsupported_action" } };
+}

package/dist/agent/cli.js

@@ -0,0 +1,360 @@
+// 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 } from "./resolve.js";
+import { buildSpec, loadAgent } from "./skill.js";
+import { validateSkill } from "./skillValidator.js";
+import { strictLint } from "./strictLint.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 } 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 lint = strictLint(raw);
+    const spec = buildSpec(raw);
+    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);
+    return { ok: true, code: 0, lines: [`wrote ${out}`, `configHash ${manifest.configHash}`] };
+}
+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);
+    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}`,
+        ];
+        const deps = {
+            client,
+            provider,
+            spec: loaded.spec,
+            mergedProse: loaded.body,
+            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.js

@@ -0,0 +1,147 @@
+// 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 } });
+    }
+    // ── 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 });
+    }
+    // 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;
+}