openbroker 1.9.1 → 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,

package/scripts/setup/install.ts

@@ -0,0 +1,146 @@
+#!/usr/bin/env npx tsx
+// Harness-aware OpenBroker installer.
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { spawnSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '../..');
+const args = new Set(process.argv.slice(2));
+
+function printUsage(): void {
+  console.log(`
+OpenBroker Harness Installer
+============================
+
+Usage:
+  openbroker install --codex [options]
+  npx openbroker@latest install --codex [options]
+
+Harnesses:
+  --codex       Install the OpenBroker skill for Codex
+
+Options:
+  --skip-cli    Do not install the persistent global CLI
+  --skip-setup  Install files without starting API-wallet onboarding
+  --help        Show this help
+
+The default Codex flow installs the global CLI, writes the skill under
+$CODEX_HOME/skills/openbroker (default: ~/.codex/skills/openbroker), and starts
+restricted API-wallet onboarding.
+`);
+}
+
+function fail(message: string): never {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+function assertOpenBrokerSkill(skillPath: string): void {
+  if (!fs.existsSync(skillPath)) return;
+
+  const existing = fs.readFileSync(skillPath, 'utf8');
+  if (!/^name:\s*openbroker\s*$/m.test(existing)) {
+    fail(`refusing to overwrite unrelated skill at ${skillPath}`);
+  }
+}
+
+function copyManagedFile(source: string, destination: string): void {
+  if (!fs.existsSync(source)) {
+    fail(`packaged installer asset is missing: ${source}`);
+  }
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true, mode: 0o755 });
+  fs.copyFileSync(source, destination);
+  fs.chmodSync(destination, 0o644);
+}
+
+function installCodexSkill(): string {
+  const codexHome = process.env.CODEX_HOME || path.join(homedir(), '.codex');
+  const destination = path.join(codexHome, 'skills', 'openbroker');
+  const skillPath = path.join(destination, 'SKILL.md');
+
+  assertOpenBrokerSkill(skillPath);
+  copyManagedFile(path.join(packageRoot, 'SKILL.md'), skillPath);
+  copyManagedFile(
+    path.join(packageRoot, 'agents', 'openai.yaml'),
+    path.join(destination, 'agents', 'openai.yaml'),
+  );
+
+  console.log(`✅ Codex skill installed: ${destination}`);
+  return destination;
+}
+
+function installGlobalCli(): void {
+  const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+  console.log('\nInstalling the persistent OpenBroker CLI...');
+  const result = spawnSync(npmCommand, ['install', '-g', 'openbroker@latest'], {
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    fail(`could not start npm: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail(
+      'global CLI installation failed. Fix the npm permission error, then rerun with --skip-cli.',
+    );
+  }
+}
+
+function runApiWalletSetup(): void {
+  const onboardPath = path.join(packageRoot, 'scripts', 'setup', 'onboard.ts');
+
+  console.log('\nStarting restricted API-wallet onboarding...\n');
+  const result = spawnSync(
+    process.execPath,
+    ['--import', 'tsx', onboardPath, '--api-wallet'],
+    {
+      stdio: 'inherit',
+      cwd: packageRoot,
+      env: process.env,
+    },
+  );
+
+  if (result.error) {
+    fail(`could not start onboarding: ${result.error.message}`);
+  }
+  if (result.status !== 0) {
+    fail('API-wallet onboarding did not complete. Rerun `openbroker setup --api-wallet`.');
+  }
+}
+
+function main(): void {
+  if (args.has('--help') || args.has('-h')) {
+    printUsage();
+    return;
+  }
+
+  if (!args.has('--codex')) {
+    printUsage();
+    fail('choose a supported harness flag such as --codex');
+  }
+
+  console.log('OpenBroker — Codex Installation');
+  console.log('================================\n');
+
+  installCodexSkill();
+
+  if (!args.has('--skip-cli')) {
+    installGlobalCli();
+  }
+
+  if (!args.has('--skip-setup')) {
+    runApiWalletSetup();
+  }
+
+  console.log('\n✅ OpenBroker installation complete.');
+  console.log('Restart Codex or start a new thread, then invoke $openbroker.');
+}
+
+main();