@raintree-technology/perps 0.1.0

package/dist/lib/agent/metrics.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { AGENT_METRICS_PATH } from "../paths.js";
+import { ensurePrivateDir, hardenPrivateFile, PRIVATE_FILE_MODE } from "../fs-security.js";
+const METRICS_SCHEMA_VERSION = 1;
+let startedAt = Date.now();
+const routes = new Map();
+const exchanges = new Map();
+function metricsPersistenceEnabled() {
+    if (process.env.PERPS_DISABLE_AGENT_METRICS_PERSISTENCE === "1") {
+        return false;
+    }
+    if (process.env.VITEST) {
+        return false;
+    }
+    return true;
+}
+function createRouteMetrics() {
+    return {
+        total: 0,
+        success: 0,
+        failure: 0,
+        latencyMsTotal: 0,
+    };
+}
+function normalizeMetricKey(value, fallback) {
+    const trimmed = value?.trim().toLowerCase();
+    if (!trimmed) {
+        return fallback;
+    }
+    return trimmed;
+}
+function entryFor(target, key) {
+    const existing = target.get(key);
+    if (existing) {
+        return existing;
+    }
+    const created = createRouteMetrics();
+    target.set(key, created);
+    return created;
+}
+function mapToRecord(target) {
+    const result = {};
+    for (const [key, value] of target.entries()) {
+        result[key] = {
+            total: value.total,
+            success: value.success,
+            failure: value.failure,
+            latencyMsTotal: value.latencyMsTotal,
+        };
+    }
+    return result;
+}
+function writeMetricsSnapshot() {
+    if (!metricsPersistenceEnabled()) {
+        return;
+    }
+    ensurePrivateDir(dirname(AGENT_METRICS_PATH));
+    const snapshot = {
+        version: METRICS_SCHEMA_VERSION,
+        startedAt,
+        updatedAt: Date.now(),
+        routes: mapToRecord(routes),
+        exchanges: mapToRecord(exchanges),
+    };
+    writeFileSync(AGENT_METRICS_PATH, `${JSON.stringify(snapshot, null, 2)}\n`, {
+        mode: PRIVATE_FILE_MODE,
+    });
+    hardenPrivateFile(AGENT_METRICS_PATH);
+}
+function hydrateMetricsSnapshot() {
+    if (!metricsPersistenceEnabled() || !existsSync(AGENT_METRICS_PATH)) {
+        return;
+    }
+    try {
+        const raw = readFileSync(AGENT_METRICS_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        const parsedStartedAt = typeof parsed.startedAt === "number" ? parsed.startedAt : Date.now();
+        startedAt = parsedStartedAt;
+        routes.clear();
+        exchanges.clear();
+        for (const [route, metric] of Object.entries(parsed.routes ?? {})) {
+            const key = normalizeMetricKey(route, "unknown");
+            routes.set(key, {
+                total: Number.isFinite(metric.total) ? metric.total : 0,
+                success: Number.isFinite(metric.success) ? metric.success : 0,
+                failure: Number.isFinite(metric.failure) ? metric.failure : 0,
+                latencyMsTotal: Number.isFinite(metric.latencyMsTotal) ? metric.latencyMsTotal : 0,
+            });
+        }
+        for (const [exchange, metric] of Object.entries(parsed.exchanges ?? {})) {
+            const key = normalizeMetricKey(exchange, "unknown");
+            exchanges.set(key, {
+                total: Number.isFinite(metric.total) ? metric.total : 0,
+                success: Number.isFinite(metric.success) ? metric.success : 0,
+                failure: Number.isFinite(metric.failure) ? metric.failure : 0,
+                latencyMsTotal: Number.isFinite(metric.latencyMsTotal) ? metric.latencyMsTotal : 0,
+            });
+        }
+    }
+    catch {
+        startedAt = Date.now();
+        routes.clear();
+        exchanges.clear();
+    }
+}
+hydrateMetricsSnapshot();
+function updateMetric(target, key, ok, latencyMs) {
+    const entry = entryFor(target, key);
+    entry.total += 1;
+    entry.latencyMsTotal += Math.max(0, latencyMs);
+    if (ok) {
+        entry.success += 1;
+    }
+    else {
+        entry.failure += 1;
+    }
+}
+export function resetAgentMetrics() {
+    startedAt = Date.now();
+    routes.clear();
+    exchanges.clear();
+    writeMetricsSnapshot();
+}
+export function recordAgentRouteMetrics(route, ok, latencyMs, exchange) {
+    const routeKey = normalizeMetricKey(route, "unknown");
+    const exchangeKey = normalizeMetricKey(exchange, "system");
+    updateMetric(routes, routeKey, ok, latencyMs);
+    updateMetric(exchanges, exchangeKey, ok, latencyMs);
+    writeMetricsSnapshot();
+}
+export function getAgentMetricsSnapshot() {
+    return {
+        startedAt,
+        routes: mapToRecord(routes),
+        exchanges: mapToRecord(exchanges),
+    };
+}
+export function getAgentReputationSummary() {
+    let totalRequests = 0;
+    let totalSuccess = 0;
+    const routeRows = [];
+    const exchangeRows = [];
+    for (const [route, metric] of routes.entries()) {
+        totalRequests += metric.total;
+        totalSuccess += metric.success;
+        const avgLatencyMs = metric.total > 0 ? metric.latencyMsTotal / metric.total : 0;
+        routeRows.push({
+            route,
+            total: metric.total,
+            successRate: metric.total > 0 ? metric.success / metric.total : 0,
+            // We do not capture distributions yet; use avg as a conservative estimate.
+            p50LatencyEstimateMs: avgLatencyMs,
+            avgLatencyMs,
+        });
+    }
+    for (const [exchange, metric] of exchanges.entries()) {
+        const avgLatencyMs = metric.total > 0 ? metric.latencyMsTotal / metric.total : 0;
+        exchangeRows.push({
+            exchange,
+            total: metric.total,
+            successRate: metric.total > 0 ? metric.success / metric.total : 0,
+            avgLatencyMs,
+        });
+    }
+    routeRows.sort((a, b) => a.route.localeCompare(b.route));
+    exchangeRows.sort((a, b) => a.exchange.localeCompare(b.exchange));
+    return {
+        uptimeMs: Date.now() - startedAt,
+        successRate: totalRequests > 0 ? totalSuccess / totalRequests : 1,
+        totalRequests,
+        routes: routeRows,
+        exchanges: exchangeRows,
+    };
+}

package/dist/lib/agent/signature.d.ts

@@ -0,0 +1,8 @@
+export interface AgentSignature {
+    signer: string;
+    requestHash: string;
+    resultHash: string;
+    signature: string;
+    algorithm: "sha256" | "hmac-sha256";
+}
+export declare function signAgentResponse(requestPayload: unknown, responsePayload: unknown): AgentSignature;

package/dist/lib/agent/signature.js

@@ -0,0 +1,28 @@
+import { createHash, createHmac } from "node:crypto";
+import { hostname } from "node:os";
+import { stableStringify } from "../stable-stringify.js";
+function hash(value) {
+    return createHash("sha256").update(stableStringify(value)).digest("hex");
+}
+export function signAgentResponse(requestPayload, responsePayload) {
+    const requestHash = hash(requestPayload);
+    const resultHash = hash(responsePayload);
+    const message = `${requestHash}:${resultHash}`;
+    const secret = process.env.PERPS_AGENT_SIGNING_SECRET?.trim();
+    if (secret) {
+        return {
+            signer: `local:${hostname()}`,
+            requestHash,
+            resultHash,
+            signature: createHmac("sha256", secret).update(message).digest("hex"),
+            algorithm: "hmac-sha256",
+        };
+    }
+    return {
+        signer: `local:${hostname()}`,
+        requestHash,
+        resultHash,
+        signature: createHash("sha256").update(message).digest("hex"),
+        algorithm: "sha256",
+    };
+}

package/dist/lib/agent/tools.d.ts

@@ -0,0 +1,28 @@
+export interface ToolExample {
+    description: string;
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+    outputSchema?: {
+        type: string;
+        description: string;
+    };
+    riskLevel: "read-only" | "mutating" | "destructive";
+    requiresAuth: boolean;
+    examples: ToolExample[];
+}
+export declare function getToolDefinitions(): ToolDefinition[];
+export declare function getToolByName(name: string): ToolDefinition | undefined;

package/dist/lib/agent/tools.js

@@ -0,0 +1,453 @@
+const TOOL_DEFINITIONS = [
+    {
+        name: "context",
+        description: "Get current portfolio state context including equity, positions, exposure, and risk limits",
+        inputSchema: {
+            type: "object",
+            properties: {
+                exchange: {
+                    type: "string",
+                    description: "Exchange to query (defaults to configured exchange)",
+                },
+            },
+        },
+        outputSchema: {
+            type: "object",
+            description: "Portfolio state context blob",
+        },
+        riskLevel: "read-only",
+        requiresAuth: true,
+        examples: [
+            {
+                description: "Get current portfolio context",
+                input: {},
+                output: {
+                    exchange: "hyperliquid",
+                    equity: 12450.32,
+                    availableBalance: 8200.1,
+                    totalExposureUsd: 4250.22,
+                    positions: [
+                        {
+                            market: "BTC-PERP",
+                            side: "long",
+                            size: "0.05",
+                            entryPrice: "67200.00",
+                            unrealizedPnl: 85.0,
+                        },
+                    ],
+                    riskLimits: {
+                        maxPositionSizeUsd: 10000,
+                        maxTotalExposureUsd: 50000,
+                        maxLeverage: 5,
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "quote",
+        description: "Get a price quote for a proposed trade including reference price, spread, and notional value",
+        inputSchema: {
+            type: "object",
+            properties: {
+                market: {
+                    type: "string",
+                    description: "Market symbol (e.g. BTC-PERP)",
+                },
+                side: {
+                    type: "string",
+                    description: "Trade direction",
+                    enum: ["long", "short"],
+                },
+                size: {
+                    type: "string",
+                    description: "Trade size in base asset units",
+                },
+            },
+            required: ["market", "side", "size"],
+        },
+        outputSchema: {
+            type: "object",
+            description: "Price quote with reference price, notional, and spread",
+        },
+        riskLevel: "read-only",
+        requiresAuth: false,
+        examples: [
+            {
+                description: "Quote for 0.1 BTC-PERP long",
+                input: { market: "BTC-PERP", side: "long", size: "0.1" },
+                output: {
+                    status: "ok",
+                    market: "BTC-PERP",
+                    side: "long",
+                    size: 0.1,
+                    quote: {
+                        referencePrice: 67250.5,
+                        notionalUsd: 6725.05,
+                        spread: 1.5,
+                        bid: 67249.75,
+                        ask: 67251.25,
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "execute",
+        description: "Execute a trade with risk policy evaluation, idempotency protection, and execution journaling",
+        inputSchema: {
+            type: "object",
+            properties: {
+                market: {
+                    type: "string",
+                    description: "Market symbol (e.g. BTC-PERP)",
+                },
+                side: {
+                    type: "string",
+                    description: "Trade direction",
+                    enum: ["long", "short"],
+                },
+                size: {
+                    type: "string",
+                    description: "Trade size in base asset units",
+                },
+                confidence: {
+                    type: "number",
+                    description: "Signal confidence score for risk sizing",
+                    default: 0.5,
+                },
+                reduceOnly: {
+                    type: "boolean",
+                    description: "Whether the order should only reduce an existing position",
+                },
+                idempotencyKey: {
+                    type: "string",
+                    description: "Unique key to prevent duplicate execution",
+                },
+            },
+            required: ["market", "side", "size"],
+        },
+        outputSchema: {
+            type: "object",
+            description: "Execution result with order details and risk metadata",
+        },
+        riskLevel: "mutating",
+        requiresAuth: true,
+        examples: [
+            {
+                description: "Buy 0.1 BTC-PERP",
+                input: {
+                    market: "BTC-PERP",
+                    side: "long",
+                    size: "0.1",
+                    confidence: 0.8,
+                    idempotencyKey: "agent-btc-001",
+                },
+                output: {
+                    status: "executed",
+                    market: "BTC-PERP",
+                    idempotency: {
+                        key: "agent-btc-001",
+                        replayed: false,
+                    },
+                    result: {
+                        order: {
+                            orderId: "abc123",
+                            fillPrice: "67250.50",
+                            filledSize: "0.1",
+                            status: "filled",
+                        },
+                        risk: {
+                            requestedSize: 0.1,
+                            adjustedSize: 0.1,
+                            adjustedNotionalUsd: 6725.05,
+                            referencePrice: 67250.5,
+                        },
+                    },
+                },
+            },
+        ],
+    },
+    {
+        name: "positions",
+        description: "Get current open positions with entry prices, unrealized PnL, and liquidation levels",
+        inputSchema: {
+            type: "object",
+            properties: {
+                exchange: {
+                    type: "string",
+                    description: "Exchange to query (defaults to configured exchange)",
+                },
+            },
+        },
+        outputSchema: {
+            type: "object",
+            description: "Array of current position objects",
+        },
+        riskLevel: "read-only",
+        requiresAuth: true,
+        examples: [
+            {
+                description: "Get all open positions",
+                input: {},
+                output: {
+                    positions: [
+                        {
+                            market: "BTC-PERP",
+                            side: "long",
+                            size: "0.05",
+                            entryPrice: "67200.00",
+                            markPrice: "67850.00",
+                            unrealizedPnl: 32.5,
+                            liquidationPrice: "58400.00",
+                            leverage: 3.2,
+                        },
+                        {
+                            market: "ETH-PERP",
+                            side: "short",
+                            size: "1.5",
+                            entryPrice: "3520.00",
+                            markPrice: "3480.00",
+                            unrealizedPnl: 60.0,
+                            liquidationPrice: "4100.00",
+                            leverage: 2.1,
+                        },
+                    ],
+                },
+            },
+        ],
+    },
+    {
+        name: "balances",
+        description: "Get current account balances including total equity, available margin, and margin usage",
+        inputSchema: {
+            type: "object",
+            properties: {
+                exchange: {
+                    type: "string",
+                    description: "Exchange to query (defaults to configured exchange)",
+                },
+            },
+        },
+        outputSchema: {
+            type: "object",
+            description: "Account balance breakdown",
+        },
+        riskLevel: "read-only",
+        requiresAuth: true,
+        examples: [
+            {
+                description: "Get current balances",
+                input: {},
+                output: {
+                    balances: [
+                        {
+                            asset: "USDC",
+                            total: "12450.32",
+                            available: "8200.10",
+                            marginUsed: "4250.22",
+                        },
+                    ],
+                },
+            },
+        ],
+    },
+    {
+        name: "markets",
+        description: "List available perpetual markets with trading pairs and metadata",
+        inputSchema: {
+            type: "object",
+            properties: {
+                exchange: {
+                    type: "string",
+                    description: "Exchange to list markets for (defaults to all available)",
+                },
+            },
+        },
+        outputSchema: {
+            type: "object",
+            description: "Array of available market objects",
+        },
+        riskLevel: "read-only",
+        requiresAuth: false,
+        examples: [
+            {
+                description: "List all markets on hyperliquid",
+                input: { exchange: "hyperliquid" },
+                output: {
+                    markets: [
+                        { symbol: "BTC-PERP", baseCurrency: "BTC", quoteCurrency: "USD" },
+                        { symbol: "ETH-PERP", baseCurrency: "ETH", quoteCurrency: "USD" },
+                        { symbol: "SOL-PERP", baseCurrency: "SOL", quoteCurrency: "USD" },
+                    ],
+                },
+            },
+        ],
+    },
+    {
+        name: "arb_compare",
+        description: "Compare funding rates and basis spreads across exchanges to identify arbitrage opportunities",
+        inputSchema: {
+            type: "object",
+            properties: {
+                assets: {
+                    type: "array",
+                    description: "List of assets to compare (e.g. [\"BTC\", \"ETH\"]). Defaults to top markets.",
+                },
+                minSpread: {
+                    type: "number",
+                    description: "Minimum annualized funding spread to include in results",
+                    default: 0.05,
+                },
+            },
+        },
+        outputSchema: {
+            type: "object",
+            description: "Cross-exchange funding rate comparison with spread calculations",
+        },
+        riskLevel: "read-only",
+        requiresAuth: false,
+        examples: [
+            {
+                description: "Compare BTC and ETH funding across exchanges",
+                input: { assets: ["BTC", "ETH"], minSpread: 0.03 },
+                output: {
+                    comparisons: [
+                        {
+                            asset: "BTC",
+                            rates: [
+                                { exchange: "hyperliquid", fundingRate: 0.0102, annualized: 0.0372 },
+                                { exchange: "vertex", fundingRate: 0.0085, annualized: 0.031 },
+                            ],
+                            spread: 0.0062,
+                        },
+                    ],
+                },
+            },
+        ],
+    },
+    {
+        name: "risk_evaluate",
+        description: "Check if a proposed order passes all active risk policy rules without executing it",
+        inputSchema: {
+            type: "object",
+            properties: {
+                market: {
+                    type: "string",
+                    description: "Market symbol (e.g. BTC-PERP)",
+                },
+                side: {
+                    type: "string",
+                    description: "Trade direction",
+                    enum: ["long", "short"],
+                },
+                sizeUsd: {
+                    type: "number",
+                    description: "Proposed position size in USD",
+                },
+                confidence: {
+                    type: "number",
+                    description: "Signal confidence for risk scaling",
+                },
+            },
+            required: ["market", "side", "sizeUsd"],
+        },
+        outputSchema: {
+            type: "object",
+            description: "Risk evaluation result with allowed/blocked status and reasoning",
+        },
+        riskLevel: "read-only",
+        requiresAuth: true,
+        examples: [
+            {
+                description: "Evaluate risk for a 5000 USD BTC long",
+                input: { market: "BTC-PERP", side: "long", sizeUsd: 5000, confidence: 0.75 },
+                output: {
+                    allowed: true,
+                    adjustedSizeUsd: 5000,
+                    adjustedSizeBase: 0.0743,
+                    referencePriceUsd: 67250.5,
+                    reason: "within risk limits",
+                    rulesEvaluated: 4,
+                    rulesPassed: 4,
+                },
+            },
+            {
+                description: "Risk evaluation blocks oversized order",
+                input: { market: "BTC-PERP", side: "long", sizeUsd: 100000 },
+                output: {
+                    allowed: false,
+                    adjustedSizeUsd: 0,
+                    adjustedSizeBase: 0,
+                    referencePriceUsd: 67250.5,
+                    reason: "exceeds maxPositionSizeUsd (10000)",
+                    rulesEvaluated: 4,
+                    rulesPassed: 2,
+                },
+            },
+        ],
+    },
+    {
+        name: "risk_rules",
+        description: "List all active risk policy rules with their current thresholds and status",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        outputSchema: {
+            type: "object",
+            description: "Array of active risk rule definitions",
+        },
+        riskLevel: "read-only",
+        requiresAuth: false,
+        examples: [
+            {
+                description: "List active risk rules",
+                input: {},
+                output: {
+                    rules: [
+                        { name: "maxPositionSizeUsd", value: 10000, enabled: true },
+                        { name: "maxTotalExposureUsd", value: 50000, enabled: true },
+                        { name: "maxLeverage", value: 5, enabled: true },
+                        { name: "minSignalConfidence", value: 0.6, enabled: true },
+                        { name: "maxDrawdownPct", value: 10, enabled: true },
+                    ],
+                },
+            },
+        ],
+    },
+    {
+        name: "operator_status",
+        description: "Get operator status including halt state, uptime, and system health indicators",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        outputSchema: {
+            type: "object",
+            description: "Operator status and halt information",
+        },
+        riskLevel: "read-only",
+        requiresAuth: false,
+        examples: [
+            {
+                description: "Check operator status",
+                input: {},
+                output: {
+                    status: "running",
+                    halted: false,
+                    uptimeMs: 3600000,
+                    defaultExchange: "hyperliquid",
+                    defaultTestnet: true,
+                    allowMainnetExecution: false,
+                },
+            },
+        ],
+    },
+];
+export function getToolDefinitions() {
+    return TOOL_DEFINITIONS;
+}
+export function getToolByName(name) {
+    return TOOL_DEFINITIONS.find((t) => t.name === name);
+}