openbroker 1.0.60 → 1.0.62

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: openbroker
-description: Hyperliquid trading plugin with background position monitoring. Execute market orders, limit orders, manage positions, view funding rates, and run trading strategies with automatic alerts for PnL changes and liquidation risk.
+description: Hyperliquid trading plugin with background position monitoring and custom automations. Execute market orders, limit orders, manage positions, view funding rates, run trading strategies, and write event-driven automation scripts with automatic alerts for PnL changes and liquidation risk.
 license: MIT
 compatibility: Requires Node.js 22+, network access to api.hyperliquid.xyz
 homepage: https://www.npmjs.com/package/openbroker
-metadata: {"author": "monemetrics", "version": "1.0.60", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
-allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status Bash(openbroker:*)
+metadata: {"author": "monemetrics", "version": "1.0.62", "openclaw": {"requires": {"bins": ["openbroker"], "env": ["HYPERLIQUID_PRIVATE_KEY"]}, "primaryEnv": "HYPERLIQUID_PRIVATE_KEY", "install": [{"id": "node", "kind": "node", "package": "openbroker", "bins": ["openbroker"], "label": "Install openbroker (npm)"}]}}
+allowed-tools: ob_account ob_positions ob_funding ob_markets ob_search ob_spot ob_fills ob_orders ob_order_status ob_fees ob_candles ob_funding_history ob_trades ob_rate_limit ob_funding_scan ob_buy ob_sell ob_limit ob_trigger ob_tpsl ob_cancel ob_twap ob_bracket ob_chase ob_watcher_status ob_auto_run ob_auto_stop ob_auto_list Bash(openbroker:*)
 ---
 
 # Open Broker - Hyperliquid Trading CLI
@@ -66,6 +66,9 @@ If an `ob_*` plugin tool returns unexpected errors, empty results, or crashes, *
 | `ob_orders` | `openbroker orders --json` |
 | `ob_funding_scan` | `openbroker funding-scan --json` |
 | `ob_candles` | `openbroker candles --coin <COIN> --json` |
+| `ob_auto_run` | `openbroker auto run <script> [--dry]` |
+| `ob_auto_stop` | (stop via SIGINT when using CLI) |
+| `ob_auto_list` | `openbroker auto list` |
 
 **When to use CLI fallback:**
 - Plugin tool returns `null`, empty data, or throws an error
@@ -448,6 +451,7 @@ This skill works standalone via Bash — every command above runs through the `o
 
 - **Structured agent tools** (`ob_account`, `ob_buy`, `ob_limit`, etc.) — typed tool calls with proper input schemas instead of Bash strings. The agent gets structured JSON responses.
 - **Background position watcher** — polls your Hyperliquid account every 30s and sends webhook alerts when positions open/close, PnL moves significantly, or margin usage gets dangerous.
+- **Automation tools** (`ob_auto_run`, `ob_auto_stop`, `ob_auto_list`) — start, stop, and manage custom trading automations from within the agent.
 - **CLI commands** — `openclaw ob status` and `openclaw ob watch` for inspecting the watcher.
 
 ### Enable the plugin
@@ -487,6 +491,243 @@ Without hooks, the watcher still runs and tracks state (accessible via `ob_watch
 - **Skill only (no plugin):** Use Bash commands (`openbroker buy --coin ETH --size 0.1`). No background monitoring.
 - **Skill + plugin:** The agent prefers the `ob_*` tools when available (structured data), falls back to Bash for commands not covered by tools (strategies, scale). Background watcher sends alerts automatically.
 
+## Trading Automations
+
+Automations let you write custom event-driven trading logic as TypeScript scripts. Instead of using the rigid built-in strategies, write exactly the logic you need and OpenBroker handles the polling, event detection, and SDK access.
+
+### How Automations Work
+
+An automation is a `.ts` file that exports a default function. The function receives an `AutomationAPI` with the full Hyperliquid client, typed event subscriptions, persistent state, and a logger. The runtime polls Hyperliquid every 10s (configurable) and dispatches events when changes are detected.
+
+### Writing an Automation
+
+Create a `.ts` file in `~/.openbroker/automations/` (or any path):
+
+```typescript
+// ~/.openbroker/automations/funding-scalp.ts
+export default function(api) {
+  const COIN = 'ETH';
+
+  api.on('funding_update', async ({ coin, annualized }) => {
+    if (coin !== COIN) return;
+
+    if (annualized > 0.5 && !api.state.get('isShort')) {
+      api.log.info('High positive funding — going short');
+      await api.client.marketOrder(COIN, false, 0.1);
+      api.state.set('isShort', true);
+    } else if (annualized < -0.1 && api.state.get('isShort')) {
+      api.log.info('Funding normalized — closing short');
+      await api.client.marketOrder(COIN, true, 0.1);
+      api.state.set('isShort', false);
+    }
+  });
+
+  api.onStop(async () => {
+    if (api.state.get('isShort')) {
+      api.log.warn('Closing short on shutdown');
+      await api.client.marketOrder('ETH', true, 0.1);
+      api.state.set('isShort', false);
+    }
+  });
+}
+```
+
+### AutomationAPI Reference
+
+| Property / Method | Description |
+|-------------------|-------------|
+| `api.client` | Full HyperliquidClient — `marketOrder()`, `limitOrder()`, `triggerOrder()`, `cancelAll()`, `getUserStateAll()`, `getAllMids()`, `updateLeverage()`, and 35+ more methods |
+| `api.on(event, handler)` | Subscribe to a market/account event (see Events below) |
+| `api.every(ms, handler)` | Run a handler on a recurring interval (aligned to poll loop) |
+| `api.onStart(handler)` | Called after all handlers are registered, before first poll |
+| `api.onStop(handler)` | Called on shutdown (SIGINT). Use for cleanup — close positions, cancel orders |
+| `api.onError(handler)` | Called when a handler throws. Error is already logged — use for recovery logic |
+| `api.state.get(key)` | Get a persisted value (survives restarts, stored in `~/.openbroker/state/`) |
+| `api.state.set(key, value)` | Set a persisted value |
+| `api.state.delete(key)` | Delete a persisted value |
+| `api.state.clear()` | Clear all state |
+| `api.publish(message, options?)` | Send a message to the OpenClaw agent via webhook. Triggers an agent turn — the agent receives the message and can notify the user, take action, etc. Returns `true` if delivered. Options: `{ name?, wakeMode?, deliver?, channel? }` |
+| `api.log.info/warn/error/debug(msg)` | Structured logger |
+| `api.utils` | `roundPrice`, `roundSize`, `sleep`, `normalizeCoin`, `formatUsd`, `annualizeFundingRate` |
+| `api.id` | Automation ID (filename or `--id` flag) |
+| `api.dryRun` | `true` if running with `--dry` (write methods are intercepted) |
+
+### Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `tick` | `{ timestamp, pollCount }` | Every poll cycle (default: 10s) |
+| `price_change` | `{ coin, oldPrice, newPrice, changePct }` | Mid price moved > 0.1% |
+| `funding_update` | `{ coin, fundingRate, annualized, premium }` | Every poll for all assets |
+| `position_opened` | `{ coin, side, size, entryPrice }` | New position detected |
+| `position_closed` | `{ coin, previousSize, entryPrice }` | Position no longer present |
+| `position_changed` | `{ coin, oldSize, newSize, entryPrice }` | Position size changed |
+| `pnl_threshold` | `{ coin, unrealizedPnl, changePct, positionValue }` | PnL moved > 5% of position value |
+| `margin_warning` | `{ marginUsedPct, equity, marginUsed }` | Margin usage > 80% |
+
+### Client Methods Available
+
+The `api.client` object exposes the full Hyperliquid SDK:
+
+**Trading:** `marketOrder(coin, isBuy, size)`, `limitOrder(coin, isBuy, size, price)`, `triggerOrder(coin, isBuy, size, triggerPx, isMarket)`, `takeProfit(coin, isBuy, size, triggerPx)`, `stopLoss(coin, isBuy, size, triggerPx)`, `cancel(coin, oid)`, `cancelAll(coin?)`
+
+**Market Data:** `getAllMids()`, `getMetaAndAssetCtxs()`, `getRecentTrades(coin)`, `getCandleSnapshot(coin, interval)`, `getFundingHistory(coin)`, `getPredictedFundings()`
+
+**Account:** `getUserStateAll()`, `getOpenOrders()`, `getUserFills()`, `getUserFunding()`, `getHistoricalOrders()`, `getUserFees()`, `getUserRateLimit()`, `getSpotBalances()`
+
+**Leverage:** `updateLeverage(coin, leverage, isIsolated?)`
+
+### Example: Price Breakout
+
+```typescript
+// ~/.openbroker/automations/breakout.ts
+export default function(api) {
+  const COIN = 'ETH';
+  const BREAKOUT_PCT = 2;  // 2% move triggers entry
+  const SIZE = 0.5;
+  let basePrice = null;
+
+  api.onStart(async () => {
+    const mids = await api.client.getAllMids();
+    basePrice = parseFloat(mids[COIN]);
+    api.log.info(`Watching ${COIN} from $${basePrice} for ${BREAKOUT_PCT}% breakout`);
+  });
+
+  api.on('price_change', async ({ coin, newPrice }) => {
+    if (coin !== COIN || !basePrice) return;
+    const totalChange = ((newPrice - basePrice) / basePrice) * 100;
+
+    if (Math.abs(totalChange) >= BREAKOUT_PCT && !api.state.get('inPosition')) {
+      const side = totalChange > 0;  // true = long, false = short
+      api.log.info(`Breakout! ${totalChange.toFixed(2)}% — entering ${side ? 'long' : 'short'}`);
+      await api.client.marketOrder(COIN, side, SIZE);
+      api.state.set('inPosition', true);
+    }
+  });
+}
+```
+
+### Example: Scheduled DCA
+
+```typescript
+// ~/.openbroker/automations/hourly-dca.ts
+export default function(api) {
+  const COIN = 'ETH';
+  const USD_PER_BUY = 100;
+
+  // Buy $100 of ETH every hour
+  api.every(60 * 60 * 1000, async () => {
+    const mids = await api.client.getAllMids();
+    const price = parseFloat(mids[COIN]);
+    const size = parseFloat(api.utils.roundSize(USD_PER_BUY / price, 4));
+    await api.client.marketOrder(COIN, true, size);
+    const count = (api.state.get('buyCount') || 0) + 1;
+    api.state.set('buyCount', count);
+    api.log.info(`DCA #${count}: bought ${size} ${COIN} at $${price}`);
+  });
+}
+```
+
+### Example: Margin Guardian
+
+```typescript
+// ~/.openbroker/automations/margin-guard.ts
+export default function(api) {
+  api.on('margin_warning', async ({ marginUsedPct, equity }) => {
+    api.log.warn(`Margin at ${marginUsedPct.toFixed(1)}% — reducing positions`);
+
+    // Close the smallest position to free margin
+    const state = await api.client.getUserStateAll();
+    const positions = state.assetPositions
+      .filter(p => parseFloat(p.position.szi) !== 0)
+      .sort((a, b) => Math.abs(parseFloat(a.position.positionValue)) - Math.abs(parseFloat(b.position.positionValue)));
+
+    if (positions.length > 0) {
+      const pos = positions[0].position;
+      const size = Math.abs(parseFloat(pos.szi));
+      const isBuy = parseFloat(pos.szi) < 0; // Close short = buy, close long = sell
+      api.log.info(`Closing smallest position: ${pos.coin} (${pos.szi})`);
+      await api.client.marketOrder(pos.coin, isBuy, size);
+    }
+  });
+}
+```
+
+### Publishing to the Agent (Webhooks)
+
+Use `api.publish()` to send messages back to the OpenClaw agent. This triggers an agent turn — the agent receives the message and can notify the user via their preferred channel, take trading actions, or log the event.
+
+```typescript
+// Simple notification
+await api.publish(`ETH broke above $4000 — current price: $${price}`);
+
+// With options
+await api.publish(`Margin at ${pct}% — positions at risk`, {
+  name: 'margin-alert',           // appears in logs
+  wakeMode: 'now',                // 'now' (default) or 'next-heartbeat'
+  channel: 'slack',               // target channel (optional)
+});
+```
+
+`api.publish()` returns `true` if delivered, `false` if webhooks are not configured (no hooks token). It requires `OPENCLAW_HOOKS_TOKEN` to be set (automatically configured when running as an OpenClaw plugin).
+
+**Example: Price alert automation with publish**
+```typescript
+// ~/.openbroker/automations/price-alert.ts
+export default function(api) {
+  const COIN = 'ETH';
+  const THRESHOLD = 4000;
+
+  api.on('price_change', async ({ coin, newPrice, changePct }) => {
+    if (coin !== COIN) return;
+
+    const crossed = api.state.get<boolean>('crossed', false);
+    if (!crossed && newPrice >= THRESHOLD) {
+      api.state.set('crossed', true);
+      await api.publish(
+        `${COIN} crossed above $${THRESHOLD}! Price: $${newPrice.toFixed(2)} (+${changePct.toFixed(2)}%)`,
+      );
+    } else if (crossed && newPrice < THRESHOLD) {
+      api.state.set('crossed', false);
+    }
+  });
+}
+```
+
+### Running Automations
+
+**CLI:**
+```bash
+openbroker auto run my-strategy --dry       # Test without trading
+openbroker auto run ./funding-scalp.ts      # Run from path
+openbroker auto run my-strategy --poll 5000 # Poll every 5s
+openbroker auto list                        # Show available scripts
+openbroker auto status                      # Show running automations
+```
+
+**Plugin tools (for OpenClaw agents):**
+- `ob_auto_run` — `{ "script": "funding-scalp", "dry": true }` — start an automation
+- `ob_auto_stop` — `{ "id": "funding-scalp" }` — stop a running automation
+- `ob_auto_list` — `{}` — list available and running automations
+
+**Options:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--dry` | Intercept write methods — no real trades | false |
+| `--verbose` | Show debug output | false |
+| `--id <name>` | Custom automation ID | filename |
+| `--poll <ms>` | Poll interval in milliseconds | 10000 |
+
+**Important notes for agents writing automations:**
+- Always test with `--dry` first before live trading
+- Use `api.state` to track position state across restarts
+- Use `api.onStop()` to clean up — close positions, cancel orders
+- Use `api.publish()` to send alerts/events back to the OpenClaw agent — do NOT manually construct webhook requests
+- The runtime catches errors per handler — one failing handler won't crash others
+- Scripts are loaded from `~/.openbroker/automations/` by name, or from any absolute path
+- All trading commands support HIP-3 assets (`api.client.marketOrder('xyz:CL', true, 1)`)
+- Automations persist across gateway restarts — they are automatically restarted when the gateway comes back up
+
 ## Risk Warning
 
 - Always use `--dry` first to preview orders

package/bin/cli.ts

@@ -52,6 +52,9 @@ const commands: Record<string, { script: string; description: string }> = {
   'dca': { script: 'strategies/dca.ts', description: 'DCA strategy' },
   'mm-spread': { script: 'strategies/mm-spread.ts', description: 'Market making (spread)' },
   'mm-maker': { script: 'strategies/mm-maker.ts', description: 'Market making (ALO)' },
+
+  // Automations
+  'auto': { script: 'auto/cli.ts', description: 'Run/manage trading automations' },
 };
 
 function printHelp() {
@@ -103,6 +106,11 @@ Strategies:
   mm-spread            Market making (spread-based)
   mm-maker             Market making (ALO orders)
 
+Automations:
+  auto run <script>    Run a custom trading automation
+  auto list            List available automations
+  auto status          Show running automations
+
 Options:
   --help, -h           Show help for a command
   --dry                Preview without executing

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openbroker",
   "name": "OpenBroker — Hyperliquid Trading",
-  "version": "1.0.60",
+  "version": "1.0.62",
   "description": "Trade on Hyperliquid DEX with background position monitoring",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbroker",
-  "version": "1.0.60",
+  "version": "1.0.62",
   "description": "Hyperliquid trading CLI - execute orders, manage positions, and run trading strategies",
   "type": "module",
   "bin": {

package/scripts/auto/cli.ts

@@ -0,0 +1,239 @@
+// CLI entry point for `openbroker auto` commands
+
+import { parseArgs } from '../core/utils.js';
+import { resolveScriptPath, listAutomations, ensureAutomationsDir } from './loader.js';
+import { startAutomation, getRunningAutomations, getRegisteredAutomations } from './runtime.js';
+import { unregisterAutomation, cleanRegistry } from './registry.js';
+
+function printUsage() {
+  console.log(`
+OpenBroker Automations — event-driven trading scripts
+
+Usage:
+  openbroker auto run <script> [options]    Run an automation script
+  openbroker auto stop <id>                 Unregister an automation (won't restart)
+  openbroker auto list                      List available automations
+  openbroker auto status                    Show running automations
+  openbroker auto clean                     Remove stale entries from registry
+
+Options (for run):
+  --dry              Intercept write methods (no real trades)
+  --verbose          Show debug output
+  --id <name>        Custom automation ID (default: filename)
+  --poll <ms>        Poll interval in milliseconds (default: 10000)
+
+Scripts are loaded from:
+  1. Absolute or relative path
+  2. ~/.openbroker/automations/<name>.ts
+
+Writing an automation:
+  export default function(api) {
+    api.on('price_change', async ({ coin, changePct }) => {
+      api.log.info(\`\${coin} moved \${changePct.toFixed(2)}%\`);
+    });
+  }
+
+Events: tick, price_change, funding_update, position_opened,
+        position_closed, position_changed, pnl_threshold, margin_warning
+
+Examples:
+  openbroker auto run my-strategy --dry     # Test without trading
+  openbroker auto run ./funding-scalp.ts    # Run from path
+  openbroker auto list                      # Show available scripts
+`);
+}
+
+async function runCommand(args: Record<string, string | boolean>, positional: string[]) {
+  const scriptName = positional[0];
+  if (!scriptName) {
+    console.error('Error: script name or path required');
+    console.log('Usage: openbroker auto run <script> [--dry] [--verbose]');
+    process.exit(1);
+  }
+
+  const scriptPath = resolveScriptPath(scriptName);
+  const dryRun = args.dry === true;
+  const verbose = args.verbose === true;
+  const pollIntervalMs = args.poll ? parseInt(String(args.poll), 10) : 10_000;
+  const id = args.id ? String(args.id) : undefined;
+
+  if (isNaN(pollIntervalMs) || pollIntervalMs < 1000) {
+    console.error('Error: --poll must be at least 1000ms');
+    process.exit(1);
+  }
+
+  const automation = await startAutomation({
+    scriptPath,
+    id,
+    dryRun,
+    verbose,
+    pollIntervalMs,
+  });
+
+  // Graceful shutdown on SIGINT/SIGTERM
+  const shutdown = async () => {
+    console.log('\nShutting down...');
+    await automation.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  // Keep process alive
+  await new Promise(() => {});
+}
+
+function listCommand() {
+  ensureAutomationsDir();
+  const automations = listAutomations();
+
+  if (automations.length === 0) {
+    console.log('No automations found in ~/.openbroker/automations/');
+    console.log('\nCreate a .ts file there with:');
+    console.log('  export default function(api) { ... }');
+    return;
+  }
+
+  console.log('Available automations:\n');
+  for (const a of automations) {
+    console.log(`  ${a.name.padEnd(30)} ${a.path}`);
+  }
+  console.log(`\nRun with: openbroker auto run <name>`);
+}
+
+function statusCommand() {
+  // Show in-process automations (if any running in this process)
+  const inProcess = getRunningAutomations();
+
+  // Show all registered automations from file-based registry (cross-process)
+  const registered = getRegisteredAutomations();
+
+  if (inProcess.length === 0 && registered.length === 0) {
+    console.log('No automations running');
+    return;
+  }
+
+  // Show in-process automations with live stats
+  if (inProcess.length > 0) {
+    console.log('Running in this process:\n');
+    for (const a of inProcess) {
+      const uptime = Math.round((Date.now() - a.startedAt.getTime()) / 1000);
+      console.log(`  ${a.id}`);
+      console.log(`    Script:  ${a.scriptPath}`);
+      console.log(`    Uptime:  ${uptime}s`);
+      console.log(`    Polls:   ${a.pollCount}`);
+      console.log(`    Events:  ${a.eventsEmitted}`);
+      console.log(`    Dry run: ${a.dryRun}`);
+      console.log('');
+    }
+  }
+
+  // Show all registered automations (may include ones from other processes)
+  const external = registered.filter(
+    r => !inProcess.some(ip => ip.id === r.id),
+  );
+
+  if (external.length > 0) {
+    if (inProcess.length > 0) console.log('Other processes:\n');
+    else console.log('Registered automations:\n');
+
+    for (const a of external) {
+      const uptime = a.status === 'running'
+        ? `${Math.round((Date.now() - new Date(a.startedAt).getTime()) / 1000)}s`
+        : '-';
+      console.log(`  ${a.id}`);
+      console.log(`    Script:  ${a.scriptPath}`);
+      console.log(`    Status:  ${a.status}${a.error ? ` (${a.error})` : ''}`);
+      console.log(`    PID:     ${a.pid}`);
+      console.log(`    Uptime:  ${uptime}`);
+      console.log(`    Dry run: ${a.dryRun}`);
+      console.log('');
+    }
+  }
+}
+
+function stopCommand(positional: string[]) {
+  const id = positional[0];
+  if (!id) {
+    console.error('Error: automation ID required');
+    console.log('Usage: openbroker auto stop <id>');
+    process.exit(1);
+  }
+
+  // Check if running in this process
+  const inProcess = getRunningAutomations();
+  const running = inProcess.find(a => a.id === id);
+  if (running) {
+    running.stop().then(() => {
+      console.log(`Stopped and unregistered: ${id}`);
+    });
+    return;
+  }
+
+  // Otherwise just remove from file registry (prevents restart)
+  unregisterAutomation(id);
+  console.log(`Unregistered: ${id} (will not restart on next gateway start)`);
+}
+
+function cleanCommand() {
+  cleanRegistry();
+  console.log('Cleaned stale entries from registry');
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+
+  if (rawArgs.length === 0 || rawArgs[0] === '--help' || rawArgs[0] === '-h') {
+    printUsage();
+    process.exit(0);
+  }
+
+  const subcommand = rawArgs[0];
+  const restArgs = rawArgs.slice(1);
+
+  // Extract positional args (non-flag args)
+  const positional: string[] = [];
+  const flagArgs: string[] = [];
+  for (let i = 0; i < restArgs.length; i++) {
+    if (restArgs[i].startsWith('--')) {
+      flagArgs.push(restArgs[i]);
+      // If next arg doesn't start with --, it's a flag value
+      if (i + 1 < restArgs.length && !restArgs[i + 1].startsWith('--')) {
+        flagArgs.push(restArgs[i + 1]);
+        i++;
+      }
+    } else {
+      positional.push(restArgs[i]);
+    }
+  }
+
+  const args = parseArgs(flagArgs);
+
+  switch (subcommand) {
+    case 'run':
+      await runCommand(args, positional);
+      break;
+    case 'stop':
+      stopCommand(positional);
+      break;
+    case 'list':
+      listCommand();
+      break;
+    case 'status':
+      statusCommand();
+      break;
+    case 'clean':
+      cleanCommand();
+      break;
+    default:
+      console.error(`Unknown subcommand: ${subcommand}`);
+      console.log('Run "openbroker auto --help" for usage');
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(err.message || err);
+  process.exit(1);
+});

package/scripts/auto/events.ts

@@ -0,0 +1,52 @@
+// Lightweight typed event bus for the automation runtime
+
+import type {
+  AutomationEventType,
+  AutomationEventPayloads,
+  AutomationEventHandler,
+} from './types.js';
+
+export class AutomationEventBus {
+  private handlers = new Map<AutomationEventType, Set<Function>>();
+
+  on<E extends AutomationEventType>(
+    event: E,
+    handler: AutomationEventHandler<E>,
+  ): void {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+  }
+
+  /** Emit an event — handlers run sequentially, errors are returned (not thrown) */
+  async emit<E extends AutomationEventType>(
+    event: E,
+    payload: AutomationEventPayloads[E],
+  ): Promise<Error[]> {
+    const set = this.handlers.get(event);
+    if (!set || set.size === 0) return [];
+
+    const errors: Error[] = [];
+    for (const handler of set) {
+      try {
+        await handler(payload);
+      } catch (err) {
+        errors.push(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+    return errors;
+  }
+
+  /** Check if any handlers are registered for an event */
+  has(event: AutomationEventType): boolean {
+    const set = this.handlers.get(event);
+    return set !== undefined && set.size > 0;
+  }
+
+  removeAll(): void {
+    this.handlers.clear();
+  }
+}

package/scripts/auto/loader.ts

@@ -0,0 +1,71 @@
+// Automation script loader — discovers and loads .ts automation files
+
+import { existsSync, readdirSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import type { AutomationFactory } from './types.js';
+
+const AUTOMATIONS_DIR = path.join(os.homedir(), '.openbroker', 'automations');
+
+/** Resolve a script path from a name or path */
+export function resolveScriptPath(nameOrPath: string): string {
+  // Absolute path
+  if (path.isAbsolute(nameOrPath)) {
+    if (!existsSync(nameOrPath)) {
+      throw new Error(`Automation script not found: ${nameOrPath}`);
+    }
+    return nameOrPath;
+  }
+
+  // Relative to cwd
+  const cwdPath = path.resolve(process.cwd(), nameOrPath);
+  if (existsSync(cwdPath)) return cwdPath;
+
+  // Relative to ~/.openbroker/automations/
+  const globalPath = path.join(AUTOMATIONS_DIR, nameOrPath);
+  if (existsSync(globalPath)) return globalPath;
+
+  // Try appending .ts
+  const withExt = path.join(AUTOMATIONS_DIR, `${nameOrPath}.ts`);
+  if (existsSync(withExt)) return withExt;
+
+  throw new Error(
+    `Automation script not found: ${nameOrPath}\n` +
+    `Searched:\n  ${cwdPath}\n  ${globalPath}\n  ${withExt}`,
+  );
+}
+
+/** Load an automation module and validate the default export */
+export async function loadAutomation(scriptPath: string): Promise<AutomationFactory> {
+  const absolutePath = path.resolve(scriptPath);
+
+  // Dynamic import — tsx handles TypeScript transpilation
+  const mod = await import(absolutePath);
+
+  const factory = mod.default;
+  if (typeof factory !== 'function') {
+    throw new Error(
+      `Automation script must export a default function.\n` +
+      `Got: ${typeof factory} from ${scriptPath}`,
+    );
+  }
+
+  return factory as AutomationFactory;
+}
+
+/** List available automation scripts in ~/.openbroker/automations/ */
+export function listAutomations(): Array<{ name: string; path: string }> {
+  if (!existsSync(AUTOMATIONS_DIR)) return [];
+
+  return readdirSync(AUTOMATIONS_DIR)
+    .filter(f => f.endsWith('.ts') && !f.startsWith('.'))
+    .map(f => ({
+      name: f.replace(/\.ts$/, ''),
+      path: path.join(AUTOMATIONS_DIR, f),
+    }));
+}
+
+/** Ensure the automations directory exists */
+export function ensureAutomationsDir(): void {
+  mkdirSync(AUTOMATIONS_DIR, { recursive: true });
+}