suprafx-agent-sdk 0.3.1

package/dist/src/mcp/preflight.js

@@ -0,0 +1,291 @@
+/**
+ * Session preflight: the checks that decide whether it is safe to trade
+ * right now, run as a first-class MCP tool instead of living in prose.
+ *
+ * Every check answers with a status and, when it is not `ok`, the ACTION
+ * that clears it — so an agent can branch on the result instead of
+ * parsing a paragraph. Run it on connect, and again after any surprise.
+ */
+import { registeredAssetId, canonicalChain } from "../derive-ids.js";
+/** A quote older than this must not be traded against. */
+export const ORACLE_STALE_MS = 120_000;
+export async function runPreflight(opts) {
+    const { client, signer, masterAddress, mode } = opts;
+    const checks = [];
+    const push = (c) => checks.push(c);
+    // ── 1. Venue reachable, and which chain is it ────────────────────
+    let chainOk = false;
+    try {
+        const ci = await client.getChainInfo();
+        chainOk = true;
+        push({
+            name: "venue_reachable",
+            status: "ok",
+            detail: `chain ${ci.chainId}, threshold ${ci.threshold}${ci.validatorCount ? ` of ${ci.validatorCount}` : ""}`,
+        });
+    }
+    catch (e) {
+        push({
+            name: "venue_reachable",
+            status: "fail",
+            detail: msg(e),
+            action: "The venue did not answer. Stop, retry once, then report — do not trade.",
+        });
+    }
+    // ── 2. Is the VENUE advancing, or only the L1? ───────────────────
+    //
+    // A stalled venue batch while the L1 keeps living looks exactly like a
+    // healthy chain from a single read. Sample the batch height twice.
+    if (chainOk) {
+        try {
+            const a = await client.getCurrentBatch();
+            await new Promise((r) => setTimeout(r, 3_000));
+            const b = await client.getCurrentBatch();
+            if (b > a) {
+                push({
+                    name: "venue_advancing",
+                    status: "ok",
+                    detail: `batch ${a} → ${b} in 3s`,
+                });
+            }
+            else {
+                push({
+                    name: "venue_advancing",
+                    status: "warn",
+                    detail: `batch height did not move in 3s (still ${a})`,
+                    action: "The venue may be batching slowly or stalled. Sample again before " +
+                        "trading; if it stays flat, stop trading and report — writes will " +
+                        "accept at ingress and never commit.",
+                });
+            }
+        }
+        catch (e) {
+            push({ name: "venue_advancing", status: "warn", detail: msg(e) });
+        }
+    }
+    // ── 3. Do the venue's own assets derive to REGISTERED ids? ───────
+    //
+    // `list_assets` returns short chain ids ("ethereum", "supra"); the
+    // AssetId derivation is keyed on canonical ones ("eth-mainnet"). If
+    // this check fails, every trade on that asset gate-rejects silently.
+    try {
+        const assets = await client.listAssets();
+        const bad = assets.filter((a) => !registeredAssetId(a.chain_id, a.asset_symbol));
+        if (assets.length === 0) {
+            push({
+                name: "assets_resolvable",
+                status: "fail",
+                detail: "list_assets returned nothing",
+                action: "Read path is broken. Reconnect, then report.",
+            });
+        }
+        else if (bad.length === 0) {
+            push({
+                name: "assets_resolvable",
+                status: "ok",
+                detail: `${assets.length}/${assets.length} venue assets derive to registered ids`,
+            });
+        }
+        else {
+            push({
+                name: "assets_resolvable",
+                status: "warn",
+                detail: `${bad.length} of ${assets.length} not in the token registry: ${bad
+                    .map((a) => `${canonicalChain(a.chain_id)}/${a.asset_symbol}`)
+                    .join(", ")}`,
+                action: "Do not trade the unlisted assets — their derived id is a placeholder " +
+                    "the validator gate rejects. Update suprafx-agent-sdk and report.",
+            });
+        }
+    }
+    catch (e) {
+        push({ name: "assets_resolvable", status: "warn", detail: msg(e) });
+    }
+    // ── 4. Oracle freshness ──────────────────────────────────────────
+    if (opts.pair) {
+        try {
+            const o = await client.getOracle(opts.pair);
+            if (o.conversionRate == null) {
+                push({
+                    name: "oracle_fresh",
+                    status: "fail",
+                    detail: `no conversionRate for ${opts.pair}`,
+                    action: "Do not quote this pair — you have no fair value.",
+                });
+            }
+            else if (o.ageMs != null && o.ageMs > ORACLE_STALE_MS) {
+                push({
+                    name: "oracle_fresh",
+                    status: "fail",
+                    detail: `${opts.pair} quote is ${Math.round(o.ageMs / 1000)}s old (limit ${ORACLE_STALE_MS / 1000}s)`,
+                    action: "Do not quote against a stale oracle. Wait for a fresh tick.",
+                });
+            }
+            else {
+                push({
+                    name: "oracle_fresh",
+                    status: "ok",
+                    detail: `${opts.pair} = ${o.conversionRate}${o.ageMs != null ? `, ${Math.round(o.ageMs / 1000)}s old` : ""}`,
+                });
+            }
+        }
+        catch (e) {
+            push({ name: "oracle_fresh", status: "warn", detail: msg(e) });
+        }
+    }
+    else {
+        push({
+            name: "oracle_fresh",
+            status: "skipped",
+            detail: "no pair given — pass `pair` to check fair-value freshness",
+        });
+    }
+    // ── 5. Custody: is a delegate key loaded, and is a master known? ──
+    if (!signer) {
+        push({
+            name: "custody",
+            status: "skipped",
+            detail: "read-only: no delegate key configured",
+            action: "Configure a delegate key to trade (see `get_setup_status`).",
+        });
+    }
+    else {
+        push({
+            name: "custody",
+            status: "ok",
+            detail: `signing as delegate ${signer.addressHex}. This key CANNOT withdraw funds — withdrawals are master-signed.`,
+        });
+        if (!masterAddress) {
+            push({
+                name: "master_address_known",
+                status: "warn",
+                detail: "no master address configured — balance reads need it",
+                action: "Ask the operator for their master StarKey address and set " +
+                    "SUPRAFX_MASTER_ADDRESS (or `masterAddress` in ~/.suprafx/config.json).",
+            });
+        }
+        else {
+            push({
+                name: "master_address_known",
+                status: "ok",
+                detail: masterAddress,
+            });
+        }
+    }
+    // ── 6. Sequence: local counter vs chain ──────────────────────────
+    if (signer) {
+        try {
+            const chainSeq = BigInt(await client.getSequenceNumber(signer.addressHex));
+            const localSeq = signer.getNextSeq();
+            if (chainSeq === localSeq) {
+                push({
+                    name: "sequence_in_sync",
+                    status: "ok",
+                    detail: `local and chain both expect seq ${localSeq}`,
+                });
+            }
+            else {
+                push({
+                    name: "sequence_in_sync",
+                    status: "fail",
+                    detail: `local seq ${localSeq}, chain expects ${chainSeq}`,
+                    action: "seq_desync — reconnect the MCP server to re-anchor. Until then " +
+                        "writes accept at ingress and are silently dropped as replays.",
+                });
+            }
+        }
+        catch (e) {
+            push({ name: "sequence_in_sync", status: "warn", detail: msg(e) });
+        }
+    }
+    // ── 7. Funded? And is anything already locked? ───────────────────
+    if (masterAddress) {
+        try {
+            const balances = await client.getBalances(masterAddress);
+            const funded = balances.filter((b) => b.total > 0);
+            const locked = balances.filter((b) => (b.locked_in_rfq ?? 0) > 0 || (b.locked_in_orders ?? 0) > 0);
+            if (funded.length === 0) {
+                push({
+                    name: "funded",
+                    status: "warn",
+                    detail: "master has no balances",
+                    action: "Deposit from the dApp (operator step). A brand-new wallet's first " +
+                        "deposit can take minutes to credit — wait and re-check, do not loop.",
+                });
+            }
+            else {
+                push({
+                    name: "funded",
+                    status: "ok",
+                    detail: funded
+                        .map((b) => `${b.asset}: ${b.available} available / ${b.total} total`)
+                        .join("; "),
+                });
+            }
+            if (locked.length > 0) {
+                push({
+                    name: "existing_locks",
+                    status: "warn",
+                    detail: locked
+                        .map((b) => `${b.asset}: ${b.locked_in_rfq} locked_in_rfq, ${b.locked_in_orders} locked_in_orders`)
+                        .join("; "),
+                    action: "Funds are already committed. Run `list_my_open_orders` to see which " +
+                        "order each lock belongs to before assuming it is a ghost-lock.",
+                });
+            }
+        }
+        catch (e) {
+            push({ name: "funded", status: "warn", detail: msg(e) });
+        }
+    }
+    // ── 8. Stale own RFQs still holding collateral ───────────────────
+    if (masterAddress) {
+        try {
+            const stale = [];
+            for (const status of ["open", "expired"]) {
+                const rows = await client.getOrderbook({ status, limit: 200 });
+                for (const r of rows) {
+                    if (r.taker_address?.toLowerCase() !== masterAddress.toLowerCase())
+                        continue;
+                    const expired = status === "expired" ||
+                        (r.expires_at ? Date.parse(r.expires_at) < Date.now() : false);
+                    if (expired)
+                        stale.push(`${r.id} (${r.pair}, ${status})`);
+                }
+            }
+            push({
+                name: "stale_own_rfqs",
+                status: stale.length === 0 ? "ok" : "warn",
+                detail: stale.length === 0
+                    ? "no expired RFQs of yours are still listed"
+                    : `${stale.length} expired RFQ(s) still listed: ${stale.join(", ")}`,
+                action: stale.length === 0
+                    ? undefined
+                    : "Each may still hold collateral. `cancel_rfq` them, then re-read get_balances.",
+            });
+        }
+        catch (e) {
+            push({ name: "stale_own_rfqs", status: "warn", detail: msg(e) });
+        }
+    }
+    const failures = checks.filter((c) => c.status === "fail");
+    const readPathOk = checks.some((c) => c.name === "venue_reachable" && c.status === "ok");
+    const readyToTrade = !!signer && failures.length === 0;
+    return {
+        ready_to_trade: readyToTrade,
+        read_path_ok: readPathOk,
+        mode,
+        checks,
+        summary: readyToTrade
+            ? `Ready to trade in ${mode} mode. ${checks.filter((c) => c.status === "warn").length} warning(s).`
+            : !signer
+                ? "Read-only: reads verified, no delegate key configured so nothing can move money."
+                : `NOT ready to trade — ${failures.length} failing check(s): ${failures
+                    .map((c) => c.name)
+                    .join(", ")}.`,
+    };
+}
+function msg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=preflight.js.map

package/dist/src/mcp/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../../src/mcp/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAErE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AA6BvC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IACvD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IACrD,MAAM,MAAM,GAAY,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,CAAC,CAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAE1C,oEAAoE;IACpE,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;QACvC,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,CAAC;YACH,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,SAAS,EAAE,CAAC,OAAO,eAAe,EAAE,CAAC,SAAS,GACpD,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EACnD,EAAE;SACH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC;YACH,IAAI,EAAE,iBAAiB;YACvB,MAAM,EAAE,MAAM;YACd,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;YACd,MAAM,EAAE,yEAAyE;SAClF,CAAC,CAAC;IACL,CAAC;IAED,oEAAoE;IACpE,EAAE;IACF,uEAAuE;IACvE,mEAAmE;IACnE,IAAI,OAAO,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC;YACzC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YAC/C,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC;YACzC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACV,IAAI,CAAC;oBACH,IAAI,EAAE,iBAAiB;oBACvB,MAAM,EAAE,IAAI;oBACZ,MAAM,EAAE,SAAS,CAAC,MAAM,CAAC,QAAQ;iBAClC,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC;oBACH,IAAI,EAAE,iBAAiB;oBACvB,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,0CAA0C,CAAC,GAAG;oBACtD,MAAM,EACJ,mEAAmE;wBACnE,mEAAmE;wBACnE,qCAAqC;iBACxC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,EAAE;IACF,mEAAmE;IACnE,oEAAoE;IACpE,qEAAqE;IACrE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;QACjF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,8BAA8B;gBACtC,MAAM,EAAE,8CAA8C;aACvD,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,wCAAwC;aAClF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,OAAO,MAAM,CAAC,MAAM,+BAA+B,GAAG;qBACxE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;qBAC7D,IAAI,CAAC,IAAI,CAAC,EAAE;gBACf,MAAM,EACJ,uEAAuE;oBACvE,kEAAkE;aACrE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,oEAAoE;IACpE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC5C,IAAI,CAAC,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACH,IAAI,EAAE,cAAc;oBACpB,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,yBAAyB,IAAI,CAAC,IAAI,EAAE;oBAC5C,MAAM,EAAE,kDAAkD;iBAC3D,CAAC,CAAC;YACL,CAAC;iBAAM,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,IAAI,CAAC,CAAC,KAAK,GAAG,eAAe,EAAE,CAAC;gBACxD,IAAI,CAAC;oBACH,IAAI,EAAE,cAAc;oBACpB,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,aAAa,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,gBACzD,eAAe,GAAG,IACpB,IAAI;oBACJ,MAAM,EAAE,6DAA6D;iBACtE,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC;oBACH,IAAI,EAAE,cAAc;oBACpB,MAAM,EAAE,IAAI;oBACZ,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,MAAM,CAAC,CAAC,cAAc,GACxC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAC7D,EAAE;iBACH,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,IAAI,EAAE,cAAc;YACpB,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,2DAA2D;SACpE,CAAC,CAAC;IACL,CAAC;IAED,qEAAqE;IACrE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,IAAI,CAAC;YACH,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,SAAS;YACjB,MAAM,EAAE,uCAAuC;YAC/C,MAAM,EAAE,6DAA6D;SACtE,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,IAAI,EAAE,SAAS;YACf,MAAM,EAAE,IAAI;YACZ,MAAM,EAAE,uBAAuB,MAAM,CAAC,UAAU,mEAAmE;SACpH,CAAC,CAAC;QACH,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,IAAI,EAAE,sBAAsB;gBAC5B,MAAM,EAAE,MAAM;gBACd,MAAM,EAAE,sDAAsD;gBAC9D,MAAM,EACJ,4DAA4D;oBAC5D,wEAAwE;aAC3E,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,IAAI,EAAE,sBAAsB;gBAC5B,MAAM,EAAE,IAAI;gBACZ,MAAM,EAAE,aAAa;aACtB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,IAAI,MAAM,EAAE,CAAC;QACX,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;YAC3E,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;YACrC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE,IAAI;oBACZ,MAAM,EAAE,mCAAmC,QAAQ,EAAE;iBACtD,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC;oBACH,IAAI,EAAE,kBAAkB;oBACxB,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,aAAa,QAAQ,mBAAmB,QAAQ,EAAE;oBAC1D,MAAM,EACJ,iEAAiE;wBACjE,+DAA+D;iBAClE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;YACzD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACnD,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAC5B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,aAAa,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,IAAI,CAAC,CAAC,GAAG,CAAC,CACnE,CAAC;YACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACH,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,wBAAwB;oBAChC,MAAM,EACJ,oEAAoE;wBACpE,sEAAsE;iBACzE,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC;oBACH,IAAI,EAAE,QAAQ;oBACd,MAAM,EAAE,IAAI;oBACZ,MAAM,EAAE,MAAM;yBACX,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,SAAS,gBAAgB,CAAC,CAAC,KAAK,QAAQ,CAAC;yBACrE,IAAI,CAAC,IAAI,CAAC;iBACd,CAAC,CAAC;YACL,CAAC;YACD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC;oBACH,IAAI,EAAE,gBAAgB;oBACtB,MAAM,EAAE,MAAM;oBACd,MAAM,EAAE,MAAM;yBACX,GAAG,CACF,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,aAAa,mBAAmB,CAAC,CAAC,gBAAgB,mBAAmB,CACzF;yBACA,IAAI,CAAC,IAAI,CAAC;oBACb,MAAM,EACJ,sEAAsE;wBACtE,gEAAgE;iBACnE,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,KAAK,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC/D,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;oBACrB,IAAI,CAAC,CAAC,aAAa,EAAE,WAAW,EAAE,KAAK,aAAa,CAAC,WAAW,EAAE;wBAAE,SAAS;oBAC7E,MAAM,OAAO,GACX,MAAM,KAAK,SAAS;wBACpB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;oBACjE,IAAI,OAAO;wBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,KAAK,MAAM,GAAG,CAAC,CAAC;gBAC5D,CAAC;YACH,CAAC;YACD,IAAI,CAAC;gBACH,IAAI,EAAE,gBAAgB;gBACtB,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;gBAC1C,MAAM,EACJ,KAAK,CAAC,MAAM,KAAK,CAAC;oBAChB,CAAC,CAAC,2CAA2C;oBAC7C,CAAC,CAAC,GAAG,KAAK,CAAC,MAAM,iCAAiC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACxE,MAAM,EACJ,KAAK,CAAC,MAAM,KAAK,CAAC;oBAChB,CAAC,CAAC,SAAS;oBACX,CAAC,CAAC,+EAA+E;aACtF,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC;IAC3D,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,iBAAiB,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;IACzF,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC;IAEvD,OAAO;QACL,cAAc,EAAE,YAAY;QAC5B,YAAY,EAAE,UAAU;QACxB,IAAI;QACJ,MAAM;QACN,OAAO,EAAE,YAAY;YACnB,CAAC,CAAC,qBAAqB,IAAI,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,MAAM,cAAc;YACnG,CAAC,CAAC,CAAC,MAAM;gBACP,CAAC,CAAC,kFAAkF;gBACpF,CAAC,CAAC,wBAAwB,QAAQ,CAAC,MAAM,sBAAsB,QAAQ;qBAClE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;qBAClB,IAAI,CAAC,IAAI,CAAC,GAAG;KACvB,CAAC;AACJ,CAAC;AAED,SAAS,GAAG,CAAC,CAAU;IACrB,OAAO,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC"}

package/dist/src/mcp/server.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MCP server wiring. Translates the `@modelcontextprotocol/sdk` tool
+ * lifecycle into calls against our handlers in `./tools.ts`.
+ *
+ * Transport: stdio (default for Claude Desktop, Cursor, Continue).
+ * The client launches `suprafx-mcp` as a subprocess and pipes JSON-RPC
+ * over stdin/stdout. No network listener on this side.
+ */
+import { type GateMode } from "./tools.js";
+export interface MCPServerOptions {
+    baseUrl?: string;
+    delegatePrivKeyHex?: string | null;
+    /** Operator's master address — balances and locks live there. */
+    masterAddress?: string | null;
+    /** `guarded` (default) requires per-call acknowledgement on money tools. */
+    mode?: GateMode;
+    /** Tool classes to expose: read / trade / cancel. */
+    groups?: Set<string>;
+}
+export declare function runMCPServer(opts?: MCPServerOptions): Promise<void>;

package/dist/src/mcp/server.js

@@ -0,0 +1,235 @@
+/**
+ * MCP server wiring. Translates the `@modelcontextprotocol/sdk` tool
+ * lifecycle into calls against our handlers in `./tools.ts`.
+ *
+ * Transport: stdio (default for Claude Desktop, Cursor, Continue).
+ * The client launches `suprafx-mcp` as a subprocess and pipes JSON-RPC
+ * over stdin/stdout. No network listener on this side.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { SupraFxClient, SupraFxError } from "../client.js";
+import { DelegateSigner } from "../signer.js";
+import { allTools, findTool, ToolError, } from "./tools.js";
+import { loadConfig } from "./config.js";
+export async function runMCPServer(opts = {}) {
+    const client = new SupraFxClient({ baseUrl: opts.baseUrl });
+    let signer = null;
+    if (opts.delegatePrivKeyHex) {
+        signer = new DelegateSigner({
+            delegatePrivKeyHex: opts.delegatePrivKeyHex,
+            client,
+        });
+        // Anchor the signer's seq counter to chain at startup.
+        try {
+            await signer.loadSequenceFromChain();
+        }
+        catch (e) {
+            // Log to stderr; signer is still usable, just with seq=0.
+            process.stderr.write(`[suprafx-mcp] warning: loadSequenceFromChain failed: ${e instanceof Error ? e.message : String(e)}\n`);
+        }
+    }
+    const ctx = {
+        client,
+        signer,
+        masterAddress: opts.masterAddress ?? null,
+        mode: opts.mode ?? "guarded",
+        groups: opts.groups ?? new Set(["read", "trade", "cancel"]),
+    };
+    // HOT-RELOAD of the delegate key. The key in `~/.suprafx/config.json`
+    // (or env) can be rotated while this long-lived stdio server runs. Without
+    // this, the signer built above is frozen for the life of the process, so
+    // after a rotation `get_my_identity` reports the stale delegate and writes
+    // sign with a stale (possibly revoked / 0-cap) key — silently. We re-read
+    // the config before every tool request and rebuild the signer ONLY when the
+    // resolved delegate key actually changes (re-anchoring its chain sequence).
+    // Steady-state cost is one small file read + string compare per call.
+    let currentKey = opts.delegatePrivKeyHex ?? null;
+    let refreshing = null;
+    // Single-flight: collapse concurrent tool-call refreshes into one, so an
+    // interleaved rotation can't trigger redundant rebuilds / racing chain reads.
+    function refreshSigner() {
+        if (!refreshing) {
+            refreshing = doRefreshSigner().finally(() => {
+                refreshing = null;
+            });
+        }
+        return refreshing;
+    }
+    async function doRefreshSigner() {
+        const cfg = loadConfig();
+        // The master address can be filled in after the server started (the
+        // operator pastes it once they find it). Pick it up on every call —
+        // it is not secret and costs nothing to re-read.
+        if (cfg.masterAddress)
+            ctx.masterAddress = cfg.masterAddress;
+        if (cfg.delegatePrivKeyHex === currentKey)
+            return; // unchanged — fast path
+        const oldAddr = ctx.signer?.addressHex ?? "none";
+        if (cfg.delegatePrivKeyHex) {
+            const next = new DelegateSigner({
+                delegatePrivKeyHex: cfg.delegatePrivKeyHex,
+                client,
+            });
+            try {
+                await next.loadSequenceFromChain();
+            }
+            catch (e) {
+                // Anchoring the new delegate's chain sequence failed (network blip).
+                // Do NOT install a seq-0 signer — it would replay-drop trades
+                // silently — and do NOT advance currentKey. Go read-only and retry
+                // the rebuild+anchor on the next tool call. Fails closed: safer than
+                // signing with a stale/old key after the operator rotated.
+                ctx.signer = null;
+                process.stderr.write(`[suprafx-mcp] warning: anchoring rotated delegate failed (${e instanceof Error ? e.message : String(e)}); staying read-only, will retry on next call\n`);
+                return; // currentKey unchanged → retried next call
+            }
+            ctx.signer = next;
+        }
+        else {
+            ctx.signer = null; // delegate removed → back to read-only
+        }
+        currentKey = cfg.delegatePrivKeyHex;
+        process.stderr.write(`[suprafx-mcp] delegate refreshed from config: ${oldAddr} -> ${ctx.signer?.addressHex ?? "none"}\n`);
+    }
+    const server = new Server({ name: "suprafx", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        await refreshSigner();
+        return {
+            tools: allTools(!!ctx.signer, ctx.groups).map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        };
+    });
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        await refreshSigner();
+        const hasSigner = !!ctx.signer;
+        const tool = findTool(req.params.name, hasSigner, ctx.groups);
+        if (!tool) {
+            // Distinguish "no such tool" from "the operator did not expose it" —
+            // different problems with different fixes.
+            const knownToSdk = findTool(req.params.name, true);
+            return mcpError(knownToSdk
+                ? {
+                    code: "TOOL_NOT_EXPOSED",
+                    detail: `${req.params.name} exists but this server was launched with ` +
+                        `--tools=${[...(ctx.groups ?? [])].join(",")}`,
+                    remedy: "the OPERATOR must relaunch the server with the class you need",
+                }
+                : {
+                    code: "UNKNOWN_TOOL",
+                    detail: `no tool named ${req.params.name}`,
+                    remedy: "call `tools/list` and use a name from it",
+                });
+        }
+        try {
+            const result = await tool.handler(req.params.arguments ?? {}, ctx);
+            if (isRejectedEnvelope(result)) {
+                return mcpError(envelopeError(result));
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, jsonReplacer, 2),
+                    },
+                ],
+            };
+        }
+        catch (e) {
+            return mcpError(normalizeError(e));
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`[suprafx-mcp] connected (delegate=${ctx.signer?.addressHex ?? "none"}, ` +
+        `master=${ctx.masterAddress ?? "unset"}, mode=${ctx.signer ? ctx.mode : "read_only"}, ` +
+        `tools=${[...(ctx.groups ?? ["read", "trade", "cancel"])].join("+")}, base=${opts.baseUrl ?? "https://suprafx.ai"}, ` +
+        `hot-reload=on)\n`);
+}
+function isRejectedEnvelope(value) {
+    return typeof value === "object" && value !== null && "ok" in value && value.ok === false;
+}
+function envelopeError(result) {
+    const upstream = result.code ? `${result.code}: ` : "";
+    const detail = result.detail ?? "the venue rejected the signed envelope";
+    if (/sequence|replay|strict.next|high.water/i.test(`${result.code ?? ""} ${detail}`)) {
+        return {
+            code: "SEQUENCE_MISMATCH",
+            detail: upstream + detail,
+            remedy: "run `get_setup_status`, re-fetch the delegate sequence number, then retry",
+        };
+    }
+    return {
+        code: "ENVELOPE_REJECTED",
+        detail: upstream + detail,
+        remedy: "run `get_setup_status`, fix the reported policy or balance issue, then retry",
+    };
+}
+/**
+ * Remedy sentence for each `SupraFxError.action`. The client layer
+ * classifies failures by CATEGORY (auth / rate_limit / seq_desync / …);
+ * this turns that category into the same `{code, detail, remedy}` shape
+ * every other error already uses, so an agent sees ONE envelope no
+ * matter which layer failed.
+ */
+const ACTION_REMEDY = {
+    authenticate: "this read needs an authorized caller — ask the operator; do not retry in a loop",
+    backoff: "back off exponentially and retry; do NOT loop",
+    fix_input: "correct the input named in detail, then retry",
+    reconnect: "reconnect the MCP server to re-anchor the delegate sequence, then retry",
+    configure_key: "configure the delegate key (`suprafx-mcp init` or SUPRAFX_DELEGATE_PRIV_HEX) and RECONNECT",
+    acknowledge: "re-send the identical call with `acknowledged: true`",
+    retry: "retry once; if it persists, report it",
+    report: "do NOT retry blindly — read state back (`get_balances`, `list_my_open_orders`) and report",
+};
+function normalizeError(e) {
+    if (e instanceof ToolError) {
+        return { code: e.code, detail: e.detail, remedy: e.remedy };
+    }
+    if (e instanceof SupraFxError) {
+        return {
+            code: e.code.toUpperCase(),
+            detail: e.message,
+            remedy: ACTION_REMEDY[e.action] ?? "run `get_setup_status`, then retry",
+        };
+    }
+    const detail = e instanceof Error ? e.message : String(e);
+    if (e instanceof TypeError ||
+        /fetch|network|timed? ?out|abort|ECONN|ENOTFOUND|GET \/api|POST \/api/i.test(detail)) {
+        return {
+            code: "NETWORK_FAILURE",
+            detail,
+            remedy: "run `get_setup_status`, verify SUPRAFX_BASE_URL and connectivity, then retry",
+        };
+    }
+    return {
+        code: "TOOL_EXECUTION_FAILED",
+        detail,
+        remedy: "run `get_setup_status`, correct the tool inputs shown in detail, then retry",
+    };
+}
+function mcpError(error) {
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(error, null, 2),
+            },
+        ],
+    };
+}
+/** JSON.stringify replacer that handles BigInt and Uint8Array. */
+function jsonReplacer(_key, value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (value instanceof Uint8Array) {
+        return "0x" + Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("");
+    }
+    return value;
+}
+//# sourceMappingURL=server.js.map

package/dist/src/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/mcp/server.ts"],"names":[],"mappings":"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"}

package/dist/src/mcp/tools.d.ts

@@ -0,0 +1,51 @@
+/**
+ * MCP tool definitions + handlers for SupraFX.
+ *
+ * DESIGN RULE: everything an agent needs in order to trade safely lives
+ * in the TOOL CONTRACT — the description it reads before calling, the
+ * lifecycle field it gets back, the structured error it gets on failure.
+ * Nothing important is left to prose in a doc the agent may never fetch.
+ *
+ * Tools are split into three classes, selectable at launch
+ * (`--tools=read,cancel`):
+ *   read   — always available, cannot move money
+ *   trade  — opens or fills a position (submit_rfq, place_quote, accept_quote)
+ *   cancel — releases a position (cancel_rfq, withdraw_quote)
+ *
+ * Reference: docs/INTEGRATING-AGENTS.md
+ */
+import type { SupraFxClient } from "../client.js";
+import type { DelegateSigner } from "../signer.js";
+export type ToolGroup = "read" | "trade" | "cancel";
+export type GateMode = "guarded" | "autonomous";
+export interface ToolContext {
+    client: SupraFxClient;
+    /** Present only when a delegate key is configured. */
+    signer: DelegateSigner | null;
+    /** The operator's master address, if known. Balances live here. */
+    masterAddress?: string | null;
+    /** `guarded` requires `acknowledged:true` on every money tool. */
+    mode?: GateMode;
+    /** Which tool classes this server was launched with. */
+    groups?: Set<string>;
+}
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: object;
+    /** Requires a configured delegate key (write tool). */
+    requiresSigner: boolean;
+    /** Tool class, for launch-time selection. Defaults to read. */
+    group?: ToolGroup;
+    /** Money-moving: gated behind `acknowledged` in guarded mode. */
+    dangerous?: boolean;
+    handler: (args: any, ctx: ToolContext) => Promise<unknown>;
+}
+export declare function allTools(hasSigner: boolean, groups?: Set<string>): ToolDef[];
+export declare function findTool(name: string, hasSigner: boolean, groups?: Set<string>): ToolDef | undefined;
+export declare class ToolError extends Error {
+    readonly code: string;
+    readonly detail: string;
+    readonly remedy: string;
+    constructor(code: string, detail: string, remedy: string);
+}