openbroker 1.9.2 → 1.9.3

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/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,CAijBzF"}

package/dist/auto/runtime.js

@@ -8,6 +8,7 @@ import { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent,
 import { WebSocketManager } from '../core/ws.js';
 import { AutomationEventBus } from './events.js';
 import { loadAutomation } from './loader.js';
+import { CLIENT_WRITE_METHODS, createGuardrailedClient } from './guardrails.js';
 import { registerAutomation, unregisterAutomation, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
 import { createAutomationAudit, toSerializable } from './audit.js';
 import { startKeepAwake } from './keep-awake.js';
@@ -74,12 +75,6 @@ function fanOutAgentAction(observers, action, status, details, txHash) {
     }
 }
 const STATE_DIR = path.join(os.homedir(), '.openbroker', 'state');
-const AUDITED_WRITE_METHODS = new Set([
-    'order', 'marketOrder', 'limitOrder', 'triggerOrder',
-    'takeProfit', 'stopLoss', 'cancel', 'cancelAll',
-    'spotOrder', 'spotMarketOrder', 'spotLimitOrder', 'spotCancel',
-    'updateLeverage', 'approveBuilderFee', 'twapOrder', 'twapCancel',
-]);
 function createState(id) {
     mkdirSync(STATE_DIR, { recursive: true });
     const stateFile = path.join(STATE_DIR, `${id}.json`);
@@ -157,18 +152,11 @@ function createLogger(id, verbose, audit) {
     };
 }
 // ── Dry-run client proxy ────────────────────────────────────────────
-const WRITE_METHODS = new Set([
-    'order', 'marketOrder', 'limitOrder', 'triggerOrder',
-    'takeProfit', 'stopLoss', 'cancel', 'cancelAll',
-    'updateLeverage', 'approveBuilderFee',
-    'spotOrder', 'spotMarketOrder', 'spotLimitOrder', 'spotCancel',
-    'twapOrder', 'twapCancel',
-]);
 function createDryClient(client, log) {
     return new Proxy(client, {
         get(target, prop, receiver) {
             const value = Reflect.get(target, prop, receiver);
-            if (typeof prop === 'string' && WRITE_METHODS.has(prop) && typeof value === 'function') {
+            if (typeof prop === 'string' && CLIENT_WRITE_METHODS.has(prop) && typeof value === 'function') {
                 return (...args) => {
                     log.info(`[DRY] ${prop}(${args.map(a => JSON.stringify(a)).join(', ')})`);
                     return Promise.resolve({ status: 'ok', response: { type: 'dry_run' } });
@@ -182,7 +170,7 @@ function createAuditedClient(client, audit, dryRun, observers) {
     return new Proxy(client, {
         get(target, prop, receiver) {
             const value = Reflect.get(target, prop, receiver);
-            if (typeof prop === 'string' && AUDITED_WRITE_METHODS.has(prop) && typeof value === 'function') {
+            if (typeof prop === 'string' && CLIENT_WRITE_METHODS.has(prop) && typeof value === 'function') {
                 return async (...args) => {
                     const actionId = `${prop}:${Date.now()}:${Math.random().toString(16).slice(2)}`;
                     audit.recordAction({
@@ -396,8 +384,39 @@ export async function startAutomation(options) {
         }
     }
     const observers = await loadConventionObservers(log);
+    let loaded;
+    try {
+        log.info(`Loading automation: ${scriptPath}`);
+        loaded = await loadAutomation(scriptPath, { config: stateController.snapshot() });
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        audit.recordError('guardrail_validation', error);
+        await audit.stop({
+            status: 'error',
+            stopReason: 'guardrail_validation_error',
+            pollCount: 0,
+            eventsEmitted: 0,
+        });
+        keepAwake?.stop();
+        throw error;
+    }
+    audit.recordNote('guardrails', loaded.guardrails);
     const baseClient = dryRun ? createDryClient(rawClient, log) : rawClient;
-    const client = createAuditedClient(baseClient, audit, dryRun, observers);
+    const guardedClient = createGuardrailedClient(baseClient, {
+        policy: loaded.guardrails,
+        rawClient,
+        log,
+        onViolation: (error, method, args) => {
+            audit.recordNote('guardrail_block', {
+                code: error.code,
+                message: error.message,
+                method,
+                args: toSerializable(args),
+            });
+        },
+    });
+    const client = createAuditedClient(guardedClient, audit, dryRun, observers);
     const startHooks = [];
     const stopHooks = [];
     const errorHooks = [];
@@ -428,12 +447,11 @@ export async function startAutomation(options) {
         audit: auditApi,
         id,
         dryRun,
+        guardrails: loaded.guardrails,
     };
     try {
-        // Load and execute the factory function (registers handlers)
-        log.info(`Loading automation: ${scriptPath}`);
-        const factory = await loadAutomation(scriptPath);
-        await factory(api);
+        // Execute the already validated factory function (registers handlers).
+        await loaded.factory(api);
         // Call onStart hooks
         for (const hook of startHooks) {
             try {

package/dist/auto/types.d.ts

@@ -1,6 +1,47 @@
 import type { HyperliquidClient } from '../core/client.js';
 /** What an automation .ts file exports */
 export type AutomationFactory = (api: AutomationAPI) => void | Promise<void>;
+/** Runtime-enforced policy exported by every automation module. */
+export type AutomationGuardrails = ReadOnlyAutomationGuardrails | TradingAutomationGuardrails;
+export interface ReadOnlyAutomationGuardrails {
+    /** Read-only automations cannot call any client write method. */
+    mode: 'read-only';
+}
+export interface TradingAutomationGuardrails {
+    mode: 'trading';
+    /** Canonical markets this automation may trade: `ETH`, `xyz:CL`, `spot:HYPE`, `#1230`. */
+    allowedMarkets: string[];
+    /** Maximum USD notional for one submitted order. */
+    maxOrderUsd: number;
+    /** Maximum absolute USD exposure in any one market after an order. */
+    maxPositionUsd: number;
+    /** Maximum absolute USD exposure across the account after an order. */
+    maxTotalExposureUsd: number;
+    /** Maximum leverage the automation may request or use when increasing perp exposure. */
+    maxLeverage: number;
+    /** Maximum account margin utilization allowed after a risk-increasing perp order. */
+    maxMarginUsedPct: number;
+    /** Maximum account-wide open orders after this automation submits an order. */
+    maxOpenOrders: number;
+    /** Maximum risk-increasing order submissions in a rolling 60-second window. */
+    maxOrdersPerMinute: number;
+    /** Maximum slippage passed to market-order helpers. */
+    maxSlippageBps: number;
+    /** Whether market-order helpers may be used. */
+    allowMarketOrders: boolean;
+    /** Whether `cancelAll()` without a market or an armed `scheduleCancel()` is allowed. */
+    allowAccountWideCancel: boolean;
+}
+export interface AutomationGuardrailContext {
+    /** Persisted automation state with current `--set` overrides applied. */
+    config: Readonly<Record<string, unknown>>;
+}
+/** Guardrails may be static or derived from startup config, but the result is always validated. */
+export type AutomationGuardrailsExport = AutomationGuardrails | ((context: AutomationGuardrailContext) => AutomationGuardrails);
+export interface LoadedAutomation {
+    factory: AutomationFactory;
+    guardrails: AutomationGuardrails;
+}
 /** Config field descriptor for example automations */
 export interface AutomationConfigField {
     type: 'string' | 'number' | 'boolean';
@@ -188,6 +229,8 @@ export interface AutomationAPI {
     id: string;
     /** True if running in --dry mode (write methods are intercepted) */
     dryRun: boolean;
+    /** Validated policy currently enforced by the runtime client proxy. */
+    guardrails: Readonly<AutomationGuardrails>;
 }
 export interface AutomationSnapshot {
     prices: Map<string, number>;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../scripts/auto/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../scripts/auto/types.ts"],"names":[],"mappings":"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"}

package/dist/lib.d.ts

@@ -11,6 +11,8 @@ export type { ChaseOptions, ChaseResult } from './operations/chase.js';
 export { startAutomation, getRunningAutomations, getAutomation, getRegisteredAutomations, } from './auto/runtime.js';
 export type { RuntimeOptions } from './auto/runtime.js';
 export { resolveScriptPath, resolveExamplePath, listAutomations, listExamples, loadExampleConfigs, ensureAutomationsDir, loadAutomation, } from './auto/loader.js';
+export { GuardrailViolation, CLIENT_WRITE_METHODS, canonicalMarket, validateAutomationGuardrails, resolveAutomationGuardrails, createGuardrailedClient, } from './auto/guardrails.js';
+export type { GuardrailedClientOptions } from './auto/guardrails.js';
 export { registerAutomation, unregisterAutomation, cleanRegistry, getAutomationsToRestart, markAutomationError, } from './auto/registry.js';
 export type * from './auto/types.js';
 //# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../scripts/lib.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,iBAAiB,EACjB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,EACX,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB,iBAAiB,CAAC;AAIrC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIvE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,mBAAmB,iBAAiB,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../scripts/lib.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,iBAAiB,EACjB,SAAS,GACV,MAAM,kBAAkB,CAAC;AAK1B,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACf,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE5E,OAAO,EACL,UAAU,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,UAAU,EACV,SAAS,EACT,KAAK,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,WAAW,EACX,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAEzB,mBAAmB,iBAAiB,CAAC;AAIrC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIvE,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,aAAa,EACb,wBAAwB,GACzB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,4BAA4B,EAC5B,2BAA2B,EAC3B,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,aAAa,EACb,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAE5B,mBAAmB,iBAAiB,CAAC"}

package/dist/lib.js

@@ -18,4 +18,5 @@ export { runChase } from './operations/chase.js';
 // ── Automation runtime ──────────────────────────────────────────────
 export { startAutomation, getRunningAutomations, getAutomation, getRegisteredAutomations, } from './auto/runtime.js';
 export { resolveScriptPath, resolveExamplePath, listAutomations, listExamples, loadExampleConfigs, ensureAutomationsDir, loadAutomation, } from './auto/loader.js';
+export { GuardrailViolation, CLIENT_WRITE_METHODS, canonicalMarket, validateAutomationGuardrails, resolveAutomationGuardrails, createGuardrailedClient, } from './auto/guardrails.js';
 export { registerAutomation, unregisterAutomation, cleanRegistry, getAutomationsToRestart, markAutomationError, } from './auto/registry.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.9.2",
+  "version": "1.9.3",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {
@@ -51,8 +51,9 @@
     "funding-scan": "tsx scripts/info/funding-scan.ts",
     "outcomes": "tsx scripts/info/outcomes.ts",
     "build": "tsc",
-    "prepublishOnly": "npm run build && npm run test:cli",
-    "test:cli": "node --import tsx bin/cli.ts --help"
+    "prepublishOnly": "npm run build && npm run test:guardrails && npm run test:cli",
+    "test:cli": "node --import tsx bin/cli.ts --help",
+    "test:guardrails": "node --import tsx --test scripts/auto/guardrails.test.ts"
   },
   "dependencies": {
     "@nktkas/hyperliquid": "^0.30.3",

package/scripts/auto/cli.ts

@@ -50,6 +50,8 @@ Scripts are loaded from:
   3. Bundled examples (via --example)
 
 Writing an automation:
+  export const guardrails = { mode: 'read-only' };
+
   export default function(api) {
     api.on('price_change', async ({ coin, changePct }) => {
       api.log.info(\`\${coin} moved \${changePct.toFixed(2)}%\`);
@@ -207,6 +209,7 @@ function listCommand() {
   if (automations.length === 0 && examples.length === 0) {
     console.log('No automations found in ~/.openbroker/automations/');
     console.log('\nCreate a .ts file there with:');
+    console.log("  export const guardrails = { mode: 'read-only' };");
     console.log('  export default function(api) { ... }');
     console.log('\nOr run a bundled example: openbroker auto examples');
     return;

package/scripts/auto/examples/dca.ts

@@ -1,6 +1,6 @@
 // DCA (Dollar Cost Averaging) — Buy fixed USD amounts at regular intervals
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Dollar cost averaging — buy fixed USD amounts at regular intervals',
@@ -12,6 +12,25 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  const amount = Number(values.amount ?? 100);
+  const count = Number(values.count ?? 24);
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: amount * 1.1,
+    maxPositionUsd: amount * count * 1.1,
+    maxTotalExposureUsd: amount * count * 1.1,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 5,
+    maxOrdersPerMinute: 5,
+    maxSlippageBps: 50,
+    allowMarketOrders: true,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function dca(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const AMOUNT_USD = api.state.get<number>('amount', 100)!;
@@ -43,7 +62,7 @@ export default function dca(api: AutomationAPI) {
     const size = AMOUNT_USD / price;
     api.log.info(`[${purchased + 1}/${MAX_PURCHASES}] Buying ~$${AMOUNT_USD} of ${COIN} @ $${price.toFixed(2)}`);
 
-    const response = await api.client.marketOrder(COIN, true, size);
+    const response = await api.client.marketOrder(COIN, true, size, undefined, 1);
     if (response.status === 'ok' && response.response && typeof response.response === 'object') {
       const status = response.response.data.statuses[0];
       if (status?.filled) {

package/scripts/auto/examples/funding-arb.ts

@@ -1,6 +1,6 @@
 // Funding Arbitrage — Collect funding by positioning opposite to the crowd
 
-import type { AutomationAPI, AutomationConfig } from '../types.js';
+import type { AutomationAPI, AutomationConfig, AutomationGuardrailContext, AutomationGuardrails } from '../types.js';
 
 export const config: AutomationConfig = {
   description: 'Funding arbitrage — collect funding by positioning opposite to the crowd',
@@ -13,6 +13,24 @@ export const config: AutomationConfig = {
   },
 };
 
+export function guardrails({ config: values }: AutomationGuardrailContext): AutomationGuardrails {
+  const sizeUsd = Number(values.sizeUsd ?? 5000);
+  return {
+    mode: 'trading',
+    allowedMarkets: [String(values.coin ?? 'HYPE')],
+    maxOrderUsd: sizeUsd * 1.1,
+    maxPositionUsd: sizeUsd * 1.1,
+    maxTotalExposureUsd: sizeUsd * 1.1,
+    maxLeverage: 1,
+    maxMarginUsedPct: 50,
+    maxOpenOrders: 5,
+    maxOrdersPerMinute: 4,
+    maxSlippageBps: 50,
+    allowMarketOrders: true,
+    allowAccountWideCancel: false,
+  };
+}
+
 export default function fundingArb(api: AutomationAPI) {
   const COIN = api.state.get<string>('coin', 'HYPE')!;
   const SIZE_USD = api.state.get<number>('sizeUsd', 5000)!;
@@ -48,7 +66,7 @@ export default function fundingArb(api: AutomationAPI) {
       if (shouldClose) {
         api.log.info(`Funding dropped to ${annualizedPct.toFixed(2)}% (below ${CLOSE_AT}%), closing ${positionSide}`);
         const closeIsBuy = positionSide === 'short';
-        await api.client.marketOrder(coin, closeIsBuy, positionSize);
+        await api.client.marketOrder(coin, closeIsBuy, positionSize, undefined, 1);
 
         inPosition = false;
         api.state.set('inPosition', false);
@@ -69,7 +87,7 @@ export default function fundingArb(api: AutomationAPI) {
       const size = SIZE_USD / price;
 
       api.log.info(`Funding at ${annualizedPct.toFixed(2)}% — opening ${side} ${size.toFixed(6)} ${coin}`);
-      const response = await api.client.marketOrder(coin, !shouldShort, size);
+      const response = await api.client.marketOrder(coin, !shouldShort, size, undefined, 1);
 
       if (response.status === 'ok' && response.response && typeof response.response === 'object') {
         const status = response.response.data.statuses[0];