openbroker 1.9.2 → 1.9.4

package/dist/auto/guardrails.test.js

@@ -0,0 +1,173 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CLIENT_WRITE_METHODS, GuardrailViolation, createGuardrailedClient, validateAutomationGuardrails, } from './guardrails.js';
+import { listExamples, loadAutomation } from './loader.js';
+const logger = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+};
+function tradingPolicy(overrides = {}) {
+    return {
+        mode: 'trading',
+        allowedMarkets: ['ETH'],
+        maxOrderUsd: 1_000,
+        maxPositionUsd: 2_000,
+        maxTotalExposureUsd: 5_000,
+        maxLeverage: 2,
+        maxMarginUsedPct: 50,
+        maxOpenOrders: 10,
+        maxOrdersPerMinute: 10,
+        maxSlippageBps: 40,
+        allowMarketOrders: true,
+        allowAccountWideCancel: false,
+        ...overrides,
+    };
+}
+function mockClient(options = {}) {
+    const calls = [];
+    const client = {
+        address: '0x0000000000000000000000000000000000000001',
+        walletAddress: '0x0000000000000000000000000000000000000002',
+        isApiWallet: true,
+        async getUserStateAll() {
+            return {
+                assetPositions: (options.positions ?? []).map((position) => ({
+                    position: {
+                        coin: position.coin,
+                        szi: String(position.size),
+                        positionValue: String(Math.abs(position.size * position.price)),
+                        leverage: { type: 'cross', value: position.leverage ?? 1 },
+                    },
+                })),
+                marginSummary: { accountValue: '10000', totalMarginUsed: '0' },
+            };
+        },
+        async getAllMids() { return { ETH: '2000', BTC: '50000' }; },
+        async getOpenOrders() { return []; },
+        async getSpotBalances() { return { balances: options.spotBalances ?? [] }; },
+        async getSpotMetaAndAssetCtxs() {
+            return options.spotData ?? { meta: { tokens: [], universe: [] }, assetCtxs: [] };
+        },
+        resolveOutcomeRef() {
+            return { outcome: 1, side: 0, encoding: 10, coin: '#10', tokenName: '+10', assetId: 100000010 };
+        },
+        async marketOrder(...args) {
+            calls.push({ method: 'marketOrder', args });
+            return { status: 'ok' };
+        },
+        async limitOrder(...args) {
+            calls.push({ method: 'limitOrder', args });
+            return { status: 'ok' };
+        },
+        async bulkOrder(...args) {
+            calls.push({ method: 'bulkOrder', args });
+            return { status: 'ok' };
+        },
+        async spotLimitOrder(...args) {
+            calls.push({ method: 'spotLimitOrder', args });
+            return { status: 'ok' };
+        },
+    };
+    return { client, calls };
+}
+test('guardrail schema rejects missing and internally inconsistent limits', () => {
+    assert.throws(() => validateAutomationGuardrails({ mode: 'trading' }), /allowedMarkets/);
+    assert.throws(() => validateAutomationGuardrails(tradingPolicy({ maxOrderUsd: 3_000 })), /maxOrderUsd.*maxPositionUsd/);
+    assert.deepEqual(validateAutomationGuardrails({ mode: 'read-only' }), { mode: 'read-only' });
+});
+test('all client write families are included in the enforcement boundary', () => {
+    for (const method of [
+        'bulkOrder', 'bulkCancel', 'scheduleCancel',
+        'outcomeOrder', 'outcomeMarketOrder', 'outcomeLimitOrder',
+    ]) {
+        assert.equal(CLIENT_WRITE_METHODS.has(method), true, `${method} must be guarded`);
+    }
+});
+test('every bundled example exports a valid guardrail policy', async () => {
+    for (const example of listExamples()) {
+        const loaded = await loadAutomation(example.path, { config: {} });
+        assert.ok(loaded.guardrails.mode === 'read-only' || loaded.guardrails.mode === 'trading');
+    }
+});
+test('read-only policy blocks every write before it reaches the client', async () => {
+    const { client, calls } = mockClient();
+    const guarded = createGuardrailedClient(client, {
+        policy: { mode: 'read-only' },
+        rawClient: client,
+        log: logger,
+    });
+    await assert.rejects(guarded.bulkOrder([{ coin: 'ETH', isBuy: true, size: 0.1, price: 2000 }]), (error) => error instanceof GuardrailViolation && error.code === 'read-only');
+    assert.equal(calls.length, 0);
+});
+test('trading policy blocks disallowed markets, missing leverage, and oversized orders', async () => {
+    const { client, calls } = mockClient();
+    const guarded = createGuardrailedClient(client, {
+        policy: tradingPolicy(),
+        rawClient: client,
+        log: logger,
+    });
+    await assert.rejects(guarded.limitOrder('BTC', true, 0.01, 50_000, 'Gtc', false, 1), (error) => error instanceof GuardrailViolation && error.code === 'market-not-allowed');
+    await assert.rejects(guarded.limitOrder('ETH', true, 0.1, 2_000), (error) => error instanceof GuardrailViolation && error.code === 'leverage-required');
+    await assert.rejects(guarded.limitOrder('ETH', true, 0.6, 2_000, 'Gtc', false, 1), (error) => error instanceof GuardrailViolation && error.code === 'order-notional');
+    assert.equal(calls.length, 0);
+});
+test('valid market orders execute with runtime-capped slippage', async () => {
+    const { client, calls } = mockClient();
+    const guarded = createGuardrailedClient(client, {
+        policy: tradingPolicy(),
+        rawClient: client,
+        log: logger,
+    });
+    await guarded.marketOrder('ETH', true, 0.1, undefined, 1);
+    assert.equal(calls.length, 1);
+    assert.deepEqual(calls[0], {
+        method: 'marketOrder',
+        args: ['ETH', true, 0.1, 40, 1],
+    });
+});
+test('account-wide exposure is checked while genuine reductions remain available above caps', async () => {
+    const exposed = mockClient({ positions: [{ coin: 'BTC', size: 0.1, price: 50_000 }] });
+    const exposureGuarded = createGuardrailedClient(exposed.client, {
+        policy: tradingPolicy({ maxTotalExposureUsd: 5_100 }),
+        rawClient: exposed.client,
+        log: logger,
+    });
+    await assert.rejects(exposureGuarded.limitOrder('ETH', true, 0.1, 2_000, 'Gtc', false, 1), (error) => error instanceof GuardrailViolation && error.code === 'total-exposure');
+    const reducing = mockClient({ positions: [{ coin: 'ETH', size: 1, price: 2_000 }] });
+    const reductionGuarded = createGuardrailedClient(reducing.client, {
+        policy: tradingPolicy({ maxPositionUsd: 1_000, maxTotalExposureUsd: 1_000 }),
+        rawClient: reducing.client,
+        log: logger,
+    });
+    await reductionGuarded.marketOrder('ETH', false, 0.1);
+    assert.equal(reducing.calls.length, 1);
+});
+test('spot exposure joins market contexts by pair identifier instead of array position', async () => {
+    const { client, calls } = mockClient({
+        spotBalances: [{ coin: 'HYPE', total: '3' }],
+        spotData: {
+            meta: {
+                tokens: [{ index: 0, name: 'USDC' }, { index: 1, name: 'HYPE' }],
+                universe: [{ name: '@107', tokens: [1, 0] }],
+            },
+            assetCtxs: [
+                { coin: '@999', midPx: '99999', markPx: '99999' },
+                { coin: '@107', midPx: '62.5', markPx: '62.5' },
+            ],
+        },
+    });
+    const guarded = createGuardrailedClient(client, {
+        policy: tradingPolicy({
+            allowedMarkets: ['spot:HYPE'],
+            maxOrderUsd: 100,
+            maxPositionUsd: 500,
+            maxTotalExposureUsd: 500,
+        }),
+        rawClient: client,
+        log: logger,
+    });
+    await guarded.spotLimitOrder('HYPE', true, 0.1, 62.5, 'Gtc');
+    assert.equal(calls.length, 1);
+});

package/dist/auto/loader.d.ts

@@ -1,4 +1,4 @@
-import type { AutomationFactory, AutomationConfig } from './types.js';
+import type { AutomationConfig, AutomationGuardrailContext, LoadedAutomation } from './types.js';
 /** Resolve a script path from a name or path */
 export declare function resolveScriptPath(nameOrPath: string): string;
 /** Resolve a bundled example by name */
@@ -10,8 +10,8 @@ export declare function listExamples(): Array<{
 }>;
 /** Load config metadata from all bundled examples */
 export declare function loadExampleConfigs(): Promise<Record<string, AutomationConfig>>;
-/** Load an automation module and validate the default export */
-export declare function loadAutomation(scriptPath: string): Promise<AutomationFactory>;
+/** Load an automation module and validate its factory plus required guardrails export. */
+export declare function loadAutomation(scriptPath: string, context?: AutomationGuardrailContext): Promise<LoadedAutomation>;
 /** List available automation scripts in ~/.openbroker/automations/ */
 export declare function listAutomations(): Array<{
     name: string;

package/dist/auto/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../scripts/auto/loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAQtE,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA2B5D;AAED,wCAAwC;AACxC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,uCAAuC;AACvC,wBAAgB,YAAY,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CASpE;AAED,qDAAqD;AACrD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAiBpF;AAmCD,gEAAgE;AAChE,wBAAsB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAenF;AAED,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CASvE;AAED,8CAA8C;AAC9C,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../scripts/auto/loader.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAEV,gBAAgB,EAChB,0BAA0B,EAE1B,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA2B5D;AAED,wCAAwC;AACxC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvD;AAED,uCAAuC;AACvC,wBAAgB,YAAY,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CASpE;AAED,qDAAqD;AACrD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAiBpF;AAmDD,0FAA0F;AAC1F,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,0BAA2C,GACnD,OAAO,CAAC,gBAAgB,CAAC,CA0B3B;AAED,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CASvE;AAED,8CAA8C;AAC9C,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/auto/loader.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, mkdirSync } from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
+import { resolveAutomationGuardrails } from './guardrails.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const AUTOMATIONS_DIR = path.join(os.homedir(), '.openbroker', 'automations');
@@ -98,8 +99,21 @@ function resolveAutomationConfig(mod) {
     }
     return null;
 }
-/** Load an automation module and validate the default export */
-export async function loadAutomation(scriptPath) {
+function resolveGuardrailsExport(mod) {
+    const candidates = [
+        mod.guardrails,
+        mod.default?.guardrails,
+        mod["module.exports"]?.guardrails,
+    ];
+    for (const candidate of candidates) {
+        if (candidate && (typeof candidate === 'object' || typeof candidate === 'function')) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/** Load an automation module and validate its factory plus required guardrails export. */
+export async function loadAutomation(scriptPath, context = { config: {} }) {
     const absolutePath = path.resolve(scriptPath);
     // Dynamic import — tsx handles TypeScript transpilation
     const mod = await import(absolutePath);
@@ -108,7 +122,15 @@ export async function loadAutomation(scriptPath) {
         throw new Error(`Automation script must export a default function.\n` +
             `Got: ${typeof factory} from ${scriptPath}`);
     }
-    return factory;
+    const guardrailsExport = resolveGuardrailsExport(mod);
+    if (!guardrailsExport) {
+        throw new Error(`Automation script must export "guardrails".\n` +
+            `Use { mode: "read-only" } for monitoring-only scripts or a validated trading policy.`);
+    }
+    return {
+        factory: factory,
+        guardrails: resolveAutomationGuardrails(guardrailsExport, context),
+    };
 }
 /** List available automation scripts in ~/.openbroker/automations/ */
 export function listAutomations() {

package/dist/auto/realtime.d.ts

@@ -0,0 +1,45 @@
+import type { AssetCtx, ClearinghouseState, OpenOrder } from '../core/types.js';
+import type { HyperliquidClient, RealtimeBookSnapshot, RealtimeDataProvider } from '../core/client.js';
+import { WebSocketManager, type WsEventMap } from '../core/ws.js';
+/**
+ * Runtime-owned WebSocket cache used transparently by HyperliquidClient read
+ * methods. While the socket is healthy, automation code calling getAllMids,
+ * getUserState(All), getSpotBalances, getMetaAndAssetCtxs, or getL2Book reads
+ * this cache. Missing/stale data returns null so the client falls back to REST.
+ */
+export declare class AutomationRealtimeData implements RealtimeDataProvider {
+    private readonly ws;
+    private readonly client;
+    private readonly user;
+    private readonly unified;
+    private readonly expectedOrderDexes;
+    private mids;
+    private assetCtxs;
+    private clearinghouse;
+    private spot;
+    private books;
+    private openOrders;
+    private bookSubscriptions;
+    private bookWaiters;
+    constructor(ws: WebSocketManager, client: HyperliquidClient, user: string, unified: boolean | null, expectedOrderDexes?: string[]);
+    get connected(): boolean;
+    getAllMids(): Record<string, string> | null;
+    getMainAssetCtxs(): AssetCtx[] | null;
+    getAllDexsAssetCtxs(): WsEventMap['allDexsAssetCtxs']['ctxs'] | null;
+    getUserState(user: string, dex?: string): ClearinghouseState | null;
+    getUserStateAll(user: string): ClearinghouseState | null;
+    getSpotBalances(user: string): ReturnType<RealtimeDataProvider['getSpotBalances']>;
+    getOpenOrders(user: string): OpenOrder[] | null;
+    getL2Book(coin: string): Promise<RealtimeBookSnapshot | null>;
+    /** Wait briefly for initial subscription snapshots before the first strategy hook runs. */
+    waitUntilReady(timeoutMs?: number): Promise<boolean>;
+    readinessSummary(): {
+        expectedOrderDexes: number;
+        seededOrderDexes: number;
+        missingOrderDexes: string[];
+    };
+    private coreFeedsReady;
+    private sameUser;
+    private fresh;
+}
+//# sourceMappingURL=realtime.d.ts.map

package/dist/auto/realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/realtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,KAAK,EACV,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAWlE;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,oBAAoB;IAW/D,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IAdrC,OAAO,CAAC,IAAI,CAA8C;IAC1D,OAAO,CAAC,SAAS,CAA8D;IAC/E,OAAO,CAAC,aAAa,CAAsF;IAC3G,OAAO,CAAC,IAAI,CAA+C;IAC3D,OAAO,CAAC,KAAK,CAAkD;IAC/D,OAAO,CAAC,UAAU,CAAyC;IAC3D,OAAO,CAAC,iBAAiB,CAAqB;IAC9C,OAAO,CAAC,WAAW,CAAsC;gBAGtC,EAAE,EAAE,gBAAgB,EACpB,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,kBAAkB,GAAE,MAAM,EAAS;IAqBtD,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAI3C,gBAAgB,IAAI,QAAQ,EAAE,GAAG,IAAI;IAOrC,mBAAmB,IAAI,UAAU,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,GAAG,IAAI;IAIpE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAmBnE,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IASxD,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAUlF,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,IAAI;IAWzC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAiCnE,2FAA2F;IACrF,cAAc,CAAC,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAS1D,gBAAgB,IAAI;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;KAAE;IASzG,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,KAAK;CAId"}

package/dist/auto/realtime.js

@@ -0,0 +1,177 @@
+const MARKET_DATA_STALE_MS = 45_000;
+const BOOK_STALE_MS = 10_000;
+const BOOK_SEED_TIMEOUT_MS = 1_500;
+/**
+ * Runtime-owned WebSocket cache used transparently by HyperliquidClient read
+ * methods. While the socket is healthy, automation code calling getAllMids,
+ * getUserState(All), getSpotBalances, getMetaAndAssetCtxs, or getL2Book reads
+ * this cache. Missing/stale data returns null so the client falls back to REST.
+ */
+export class AutomationRealtimeData {
+    ws;
+    client;
+    user;
+    unified;
+    expectedOrderDexes;
+    mids = null;
+    assetCtxs = null;
+    clearinghouse = null;
+    spot = null;
+    books = new Map();
+    openOrders = new Map();
+    bookSubscriptions = new Set();
+    bookWaiters = new Map();
+    constructor(ws, client, user, unified, expectedOrderDexes = ['']) {
+        this.ws = ws;
+        this.client = client;
+        this.user = user;
+        this.unified = unified;
+        this.expectedOrderDexes = expectedOrderDexes;
+        ws.on('allMids', (data) => { this.mids = { value: data.mids, timestamp: Date.now() }; });
+        ws.on('allDexsAssetCtxs', (data) => { this.assetCtxs = { value: data.ctxs, timestamp: Date.now() }; });
+        ws.on('allDexsClearinghouseState', (data) => {
+            this.clearinghouse = { value: data.clearinghouseStates, timestamp: Date.now() };
+        });
+        ws.on('spotState', (data) => { this.spot = { value: data, timestamp: Date.now() }; });
+        ws.on('openOrders', (data) => {
+            if (this.sameUser(data.user))
+                this.openOrders.set(data.dex || '', { value: data.orders, timestamp: Date.now() });
+        });
+        ws.on('l2Book', (data) => {
+            this.books.set(data.coin, { value: data, timestamp: Date.now() });
+            const waiters = this.bookWaiters.get(data.coin);
+            if (waiters) {
+                for (const resolve of waiters)
+                    resolve();
+                waiters.clear();
+            }
+        });
+    }
+    get connected() {
+        return this.ws.connected;
+    }
+    getAllMids() {
+        return this.fresh(this.mids, MARKET_DATA_STALE_MS)?.value ?? null;
+    }
+    getMainAssetCtxs() {
+        const groups = this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value;
+        if (!groups)
+            return null;
+        const main = groups.find(([dex]) => !dex || dex === 'main') ?? groups[0];
+        return main?.[1] ?? null;
+    }
+    getAllDexsAssetCtxs() {
+        return this.fresh(this.assetCtxs, MARKET_DATA_STALE_MS)?.value ?? null;
+    }
+    getUserState(user, dex) {
+        if (!this.sameUser(user))
+            return null;
+        const groups = this.clearinghouse?.value;
+        if (!groups)
+            return null;
+        const targetDex = dex ?? '';
+        const raw = groups.find(([name]) => (name || '') === targetDex)?.[1];
+        if (!raw)
+            return null;
+        const withdrawable = raw.withdrawable;
+        return {
+            ...raw,
+            marginSummary: raw.marginSummary && withdrawable != null
+                ? { ...raw.marginSummary, withdrawable }
+                : raw.marginSummary,
+            crossMarginSummary: raw.crossMarginSummary && withdrawable != null
+                ? { ...raw.crossMarginSummary, withdrawable }
+                : raw.crossMarginSummary,
+        };
+    }
+    getUserStateAll(user) {
+        if (!this.sameUser(user) || !this.clearinghouse || this.unified === null)
+            return null;
+        return this.client.userStateAllFromWs(this.clearinghouse.value, this.unified, this.spot ? { balances: this.spot.value.balances } : undefined);
+    }
+    getSpotBalances(user) {
+        if (!this.sameUser(user) || !this.spot)
+            return null;
+        return {
+            balances: this.spot.value.balances.map((balance) => ({
+                ...balance,
+                entryNtl: balance.entryNtl ?? '0',
+            })),
+        };
+    }
+    getOpenOrders(user) {
+        if (!this.sameUser(user) || !this.connected)
+            return null;
+        const orders = [];
+        for (const dex of new Set(['', ...this.expectedOrderDexes])) {
+            const entry = this.openOrders.get(dex);
+            if (!entry)
+                return null;
+            orders.push(...entry.value);
+        }
+        return orders;
+    }
+    async getL2Book(coin) {
+        const cached = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+        if (cached)
+            return cached.value;
+        if (!this.connected)
+            return null;
+        if (!this.bookSubscriptions.has(coin)) {
+            this.bookSubscriptions.add(coin);
+            try {
+                await this.ws.subscribeL2Book(coin);
+            }
+            catch {
+                this.bookSubscriptions.delete(coin);
+                return null;
+            }
+        }
+        const seeded = this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS);
+        if (seeded)
+            return seeded.value;
+        await new Promise((resolve) => {
+            const waiters = this.bookWaiters.get(coin) ?? new Set();
+            this.bookWaiters.set(coin, waiters);
+            const done = () => {
+                clearTimeout(timer);
+                waiters.delete(done);
+                resolve();
+            };
+            const timer = setTimeout(done, BOOK_SEED_TIMEOUT_MS);
+            waiters.add(done);
+        });
+        return this.fresh(this.books.get(coin) ?? null, BOOK_STALE_MS)?.value ?? null;
+    }
+    /** Wait briefly for initial subscription snapshots before the first strategy hook runs. */
+    async waitUntilReady(timeoutMs = 10_000) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (this.coreFeedsReady())
+                return true;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        return this.coreFeedsReady();
+    }
+    readinessSummary() {
+        const expected = [...new Set(['', ...this.expectedOrderDexes])];
+        return {
+            expectedOrderDexes: expected.length,
+            seededOrderDexes: expected.filter((dex) => this.openOrders.has(dex)).length,
+            missingOrderDexes: expected.filter((dex) => !this.openOrders.has(dex)),
+        };
+    }
+    coreFeedsReady() {
+        const ordersReady = [...new Set(['', ...this.expectedOrderDexes])]
+            .every((dex) => this.openOrders.has(dex));
+        return Boolean(this.mids && this.assetCtxs && this.clearinghouse && this.spot && ordersReady);
+    }
+    sameUser(user) {
+        return user.toLowerCase() === this.user.toLowerCase();
+    }
+    fresh(entry, maxAgeMs) {
+        if (!this.connected || !entry || Date.now() - entry.timestamp > maxAgeMs)
+            return null;
+        return entry;
+    }
+}

package/dist/auto/realtime.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=realtime.test.d.ts.map

package/dist/auto/realtime.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.test.d.ts","sourceRoot":"","sources":["../../scripts/auto/realtime.test.ts"],"names":[],"mappings":""}

package/dist/auto/realtime.test.js

@@ -0,0 +1,73 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { AutomationRealtimeData } from './realtime.js';
+class FakeWebSocket {
+    connected = true;
+    handlers = new Map();
+    on(event, handler) {
+        const set = this.handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.handlers.set(event, set);
+    }
+    emit(event, value) {
+        for (const handler of this.handlers.get(event) ?? [])
+            handler(value);
+    }
+    async subscribeL2Book(coin) {
+        queueMicrotask(() => this.emit('l2Book', {
+            coin,
+            time: Date.now(),
+            levels: [
+                [{ px: '99', sz: '2', n: 1 }],
+                [{ px: '101', sz: '3', n: 1 }],
+            ],
+        }));
+        return {};
+    }
+}
+const ADDRESS = '0x0000000000000000000000000000000000000001';
+test('realtime cache serves subscribed market/account data and seeds books on demand', async () => {
+    const ws = new FakeWebSocket();
+    const mergedState = {
+        assetPositions: [],
+        marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+        crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+        crossMaintenanceMarginUsed: '0',
+    };
+    const client = {
+        userStateAllFromWs: () => mergedState,
+    };
+    const cache = new AutomationRealtimeData(ws, client, ADDRESS, true);
+    ws.emit('allMids', { mids: { HYPE: '100' } });
+    ws.emit('allDexsAssetCtxs', { ctxs: [['', [{ funding: '0.0001', openInterest: '1', dayNtlVlm: '2', premium: '0', oraclePx: '100', markPx: '100', prevDayPx: '99' }]]] });
+    ws.emit('spotState', { balances: [{ coin: 'USDC', token: 0, total: '100', hold: '0' }] });
+    ws.emit('openOrders', { user: ADDRESS, dex: '', orders: [] });
+    ws.emit('allDexsClearinghouseState', {
+        user: ADDRESS,
+        clearinghouseStates: [['', {
+                    assetPositions: [],
+                    marginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+                    crossMarginSummary: { accountValue: '100', totalNtlPos: '0', totalRawUsd: '100', totalMarginUsed: '0', withdrawable: '100' },
+                    crossMaintenanceMarginUsed: '0',
+                    withdrawable: '100',
+                }]],
+    });
+    assert.equal(await cache.waitUntilReady(20), true);
+    assert.equal(cache.getAllMids()?.HYPE, '100');
+    assert.equal(cache.getMainAssetCtxs()?.[0]?.funding, '0.0001');
+    assert.equal(cache.getSpotBalances(ADDRESS)?.balances[0]?.entryNtl, '0');
+    assert.deepEqual(cache.getOpenOrders(ADDRESS), []);
+    assert.equal(cache.getUserState(ADDRESS)?.marginSummary.accountValue, '100');
+    assert.equal(cache.getUserStateAll(ADDRESS)?.marginSummary.accountValue, '100');
+    const book = await cache.getL2Book('HYPE');
+    assert.equal(book?.levels[0][0]?.px, '99');
+    assert.equal(book?.levels[1][0]?.px, '101');
+});
+test('realtime cache declines reads while disconnected so the client can fall back to REST', () => {
+    const ws = new FakeWebSocket();
+    const client = { userStateAllFromWs: () => null };
+    const cache = new AutomationRealtimeData(ws, client, ADDRESS, false);
+    ws.emit('allMids', { mids: { HYPE: '100' } });
+    ws.connected = false;
+    assert.equal(cache.getAllMids(), null);
+});

package/dist/auto/runtime.d.ts

@@ -13,9 +13,9 @@ export interface RuntimeOptions {
     /** Pre-seed state before the factory function runs (e.g. from --set key=value) */
     initialState?: Record<string, unknown>;
     /**
-     * Enable WebSocket for real-time events (allMids, orderUpdates, userFills, userEvents).
-     * When enabled, REST polling interval is relaxed to a heartbeat (default 60s).
-     * Falls back gracefully to polling if WebSocket connection fails.
+     * Enable WebSocket-first market/account data and events. REST is used for
+     * initial static metadata, minute reconciliation, and automatic fallback
+     * while the socket is unavailable.
      * @default true
      */
     useWebSocket?: boolean;

package/dist/auto/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/runtime.ts"],"names":[],"mappings":"AAeA,OAAO,EAA4C,wBAAwB,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG5H,OAAO,KAAK,EAYV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAoZpB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvE;AAED,8EAA8E;AAC9E,OAAO,EAAE,qBAAqB,IAAI,wBAAwB,EAAE,CAAC;AAE7D,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAohBzF"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../scripts/auto/runtime.ts"],"names":[],"mappings":"AAgBA,OAAO,EAA4C,wBAAwB,IAAI,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAG5H,OAAO,KAAK,EAYV,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAqYpB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAKD,wBAAgB,qBAAqB,IAAI,iBAAiB,EAAE,CAE3D;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,GAAG,SAAS,CAEvE;AAED,8EAA8E;AAC9E,OAAO,EAAE,qBAAqB,IAAI,wBAAwB,EAAE,CAAC;AAE7D,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+nBzF"}