openbroker 1.9.2 → 1.9.3

package/scripts/auto/loader.ts

@@ -4,7 +4,14 @@ import { existsSync, readdirSync, mkdirSync } from 'fs';
 import path from 'path';
 import os from 'os';
 import { fileURLToPath } from 'url';
-import type { AutomationFactory, AutomationConfig } from './types.js';
+import { resolveAutomationGuardrails } from './guardrails.js';
+import type {
+  AutomationFactory,
+  AutomationConfig,
+  AutomationGuardrailContext,
+  AutomationGuardrailsExport,
+  LoadedAutomation,
+} from './types.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -117,8 +124,27 @@ function resolveAutomationConfig(mod: Record<string, unknown>): AutomationConfig
   return null;
 }
 
-/** Load an automation module and validate the default export */
-export async function loadAutomation(scriptPath: string): Promise<AutomationFactory> {
+function resolveGuardrailsExport(mod: Record<string, unknown>): AutomationGuardrailsExport | null {
+  const candidates = [
+    mod.guardrails,
+    (mod.default as Record<string, unknown> | undefined)?.guardrails,
+    (mod["module.exports"] as Record<string, unknown> | undefined)?.guardrails,
+  ];
+
+  for (const candidate of candidates) {
+    if (candidate && (typeof candidate === 'object' || typeof candidate === 'function')) {
+      return candidate as AutomationGuardrailsExport;
+    }
+  }
+
+  return null;
+}
+
+/** Load an automation module and validate its factory plus required guardrails export. */
+export async function loadAutomation(
+  scriptPath: string,
+  context: AutomationGuardrailContext = { config: {} },
+): Promise<LoadedAutomation> {
   const absolutePath = path.resolve(scriptPath);
 
   // Dynamic import — tsx handles TypeScript transpilation
@@ -132,7 +158,18 @@ export async function loadAutomation(scriptPath: string): Promise<AutomationFact
     );
   }
 
-  return factory as AutomationFactory;
+  const guardrailsExport = resolveGuardrailsExport(mod as Record<string, unknown>);
+  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 as AutomationFactory,
+    guardrails: resolveAutomationGuardrails(guardrailsExport, context),
+  };
 }
 
 /** List available automation scripts in ~/.openbroker/automations/ */

package/scripts/auto/runtime.ts

@@ -13,6 +13,7 @@ import {
 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, type AutomationAuditSink } from './audit.js';
 import { startKeepAwake, type KeepAwakeHandle } from './keep-awake.js';
@@ -29,6 +30,7 @@ import type {
   PublishOptions,
   ScheduledTask,
   RunningAutomation,
+  LoadedAutomation,
 } from './types.js';
 
 // ── Observer fan-out ────────────────────────────────────────────────
@@ -105,13 +107,6 @@ function fanOutAgentAction(
 }
 
 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',
-]);
-
 // ── State persistence ───────────────────────────────────────────────
 
 interface StateController {
@@ -202,19 +197,11 @@ function createLogger(id: string, verbose: boolean, audit?: AutomationAuditSink)
 
 // ── 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: HyperliquidClient, log: AutomationLogger): HyperliquidClient {
   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: unknown[]) => {
           log.info(`[DRY] ${prop}(${args.map(a => JSON.stringify(a)).join(', ')})`);
           return Promise.resolve({ status: 'ok', response: { type: 'dry_run' } });
@@ -234,7 +221,7 @@ function createAuditedClient(
   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: unknown[]) => {
           const actionId = `${prop}:${Date.now()}:${Math.random().toString(16).slice(2)}`;
           audit.recordAction({
@@ -531,8 +518,38 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     }
   }
   const observers = await loadConventionObservers(log);
+  let loaded: LoadedAutomation;
+  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: Array<() => void | Promise<void>> = [];
   const stopHooks: Array<() => void | Promise<void>> = [];
@@ -565,13 +582,12 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     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) {

package/scripts/auto/types.ts

@@ -8,6 +8,57 @@ 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';
@@ -206,6 +257,9 @@ export interface AutomationAPI {
 
   /** True if running in --dry mode (write methods are intercepted) */
   dryRun: boolean;
+
+  /** Validated policy currently enforced by the runtime client proxy. */
+  guardrails: Readonly<AutomationGuardrails>;
 }
 
 // ── Runtime internals ───────────────────────────────────────────────

package/scripts/lib.ts

@@ -79,6 +79,16 @@ export {
   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,