openbroker 1.0.61 → 1.0.63

package/SKILL.md

@@ -4,7 +4,7 @@ description: Hyperliquid trading plugin with background position monitoring and
 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.61", "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)"}]}}
+metadata: {"author": "monemetrics", "version": "1.0.63", "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:*)
 ---
 
@@ -546,6 +546,7 @@ export default function(api) {
 | `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) |
@@ -556,7 +557,7 @@ export default function(api) {
 | Event | Payload | When |
 |-------|---------|------|
 | `tick` | `{ timestamp, pollCount }` | Every poll cycle (default: 10s) |
-| `price_change` | `{ coin, oldPrice, newPrice, changePct }` | Mid price moved > 0.1% |
+| `price_change` | `{ coin, oldPrice, newPrice, changePct }` | Mid price moved > 0.01% between polls |
 | `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 |
@@ -564,6 +565,200 @@ export default function(api) {
 | `pnl_threshold` | `{ coin, unrealizedPnl, changePct, positionValue }` | PnL moved > 5% of position value |
 | `margin_warning` | `{ marginUsedPct, equity, marginUsed }` | Margin usage > 80% |
 
+### Event Details — Choosing the Right Event
+
+#### `tick` — The universal heartbeat
+Fires **every single poll cycle** (default: 10s) regardless of market conditions. Use this when you need to check something on every poll — absolute price thresholds, custom conditions, periodic account checks. This is the most reliable event because it always fires.
+
+**Payload:** `{ timestamp: number, pollCount: number }`
+
+**When to use:**
+- Checking if a price is above/below an absolute threshold (e.g. "alert me when ETH < $3000")
+- Custom conditions that don't fit other events (e.g. "if I have no positions and funding is high, enter")
+- Periodic tasks that need to run every poll (though `api.every()` is better for longer intervals)
+
+**Example — absolute price alert:**
+```typescript
+api.on('tick', async () => {
+  const mids = await api.client.getAllMids();
+  const price = parseFloat(mids['HYPE']);
+  if (price < 38 && !api.state.get('alerted')) {
+    api.state.set('alerted', true);
+    await api.publish(`HYPE dropped below $38 — now at $${price.toFixed(3)}`);
+  }
+});
+```
+
+**Note:** `tick` does not include price data in its payload — you must fetch it yourself via `api.client.getAllMids()`. This is because tick fires before any other event processing. If you only care about price movements, use `price_change` instead.
+
+#### `price_change` — Relative price movements
+Fires when a coin's mid price moves **≥ 0.01%** compared to the previous poll. This filters out rounding noise while catching virtually any real price movement. The comparison is between consecutive polls (not from a fixed baseline), so it detects incremental changes.
+
+**Payload:** `{ coin: string, oldPrice: number, newPrice: number, changePct: number }`
+
+**When to use:**
+- Reacting to price movements (breakouts, momentum, mean reversion)
+- Monitoring specific coins for volatility
+- Building price-triggered entry/exit logic
+
+**When NOT to use:**
+- Checking if price is above/below a fixed threshold — use `tick` instead, because `price_change` only fires on relative movement between polls. During slow drifts (e.g. price slowly declining $0.001/s), the change between any two 10s polls may be < 0.01%, so the event won't fire even though the price has crossed your threshold.
+
+**Example — momentum detector:**
+```typescript
+api.on('price_change', async ({ coin, changePct, newPrice }) => {
+  if (coin !== 'ETH') return;
+  if (changePct > 0.5) {
+    api.log.info(`ETH surging +${changePct.toFixed(2)}% — price $${newPrice}`);
+    // Enter long on strong upward momentum
+  }
+});
+```
+
+#### `funding_update` — Funding rate data
+Fires **every poll** for **every asset** that has funding rate data. This is high-frequency — if there are 150 perp assets, this fires 150 times per poll. Filter by coin in your handler.
+
+**Payload:** `{ coin: string, fundingRate: number, annualized: number, premium: number }`
+- `fundingRate` — the raw hourly funding rate (e.g. 0.0001 = 0.01%/hr)
+- `annualized` — annualized rate (fundingRate × 8760 × 100, as a percentage)
+- `premium` — the premium component
+
+**When to use:**
+- Funding rate arbitrage strategies
+- Monitoring for extreme funding (entry/exit signals)
+- Scanning for highest/lowest funding across all assets
+
+**Example — funding scalp:**
+```typescript
+api.on('funding_update', async ({ coin, annualized }) => {
+  if (coin !== 'ETH') return;
+  if (annualized > 50 && !api.state.get('isShort')) {
+    api.log.info(`ETH funding at ${annualized.toFixed(1)}% annualized — shorting`);
+    await api.client.marketOrder('ETH', false, 0.1);
+    api.state.set('isShort', true);
+  }
+});
+```
+
+#### `position_opened` — New position detected
+Fires when a position appears that wasn't present in the previous poll. Useful for tracking entries made by other systems or confirming your own orders filled.
+
+**Payload:** `{ coin: string, side: 'long' | 'short', size: number, entryPrice: number }`
+
+**When to use:**
+- Setting TP/SL on new positions automatically
+- Logging/alerting when positions are opened (by you or another system)
+- Starting position-specific monitoring
+
+**Example — auto TP/SL on new positions:**
+```typescript
+api.on('position_opened', async ({ coin, side, size, entryPrice }) => {
+  const tpPrice = side === 'long' ? entryPrice * 1.05 : entryPrice * 0.95;
+  const slPrice = side === 'long' ? entryPrice * 0.97 : entryPrice * 1.03;
+  await api.client.takeProfit(coin, side !== 'long', size, tpPrice);
+  await api.client.stopLoss(coin, side !== 'long', size, slPrice);
+  api.log.info(`Set TP at ${tpPrice} / SL at ${slPrice} for ${coin}`);
+});
+```
+
+#### `position_closed` — Position gone
+Fires when a position that existed in the previous poll is no longer present. The position was either closed by you, liquidated, or filled by TP/SL.
+
+**Payload:** `{ coin: string, previousSize: number, entryPrice: number }`
+
+**When to use:**
+- Logging/alerting when positions close
+- Cleaning up related orders or state
+- Re-entry logic after a position closes
+
+**Example:**
+```typescript
+api.on('position_closed', async ({ coin, previousSize, entryPrice }) => {
+  api.log.info(`${coin} position closed (was ${previousSize} @ ${entryPrice})`);
+  api.state.delete(`${coin}_tp`);
+  await api.publish(`Position closed: ${coin} (entry: $${entryPrice})`);
+});
+```
+
+#### `position_changed` — Size or direction changed
+Fires when an existing position's size changes (partial close, add to position, or flip direction). Does NOT fire when a new position opens or an existing one fully closes — use `position_opened` and `position_closed` for those.
+
+**Payload:** `{ coin: string, oldSize: number, newSize: number, entryPrice: number }`
+- `oldSize`/`newSize` are signed: positive = long, negative = short
+
+**When to use:**
+- Detecting partial closes or position scaling
+- Adjusting TP/SL when position size changes
+- Tracking DCA entries
+
+**Example:**
+```typescript
+api.on('position_changed', async ({ coin, oldSize, newSize }) => {
+  if (Math.abs(newSize) > Math.abs(oldSize)) {
+    api.log.info(`${coin} position increased: ${oldSize} → ${newSize}`);
+  } else {
+    api.log.info(`${coin} position reduced: ${oldSize} → ${newSize}`);
+  }
+});
+```
+
+#### `pnl_threshold` — Significant PnL movement
+Fires when unrealized PnL changes by **≥ 5% of position value** between consecutive polls. This is a large move detector — useful for risk management alerts rather than routine monitoring.
+
+**Payload:** `{ coin: string, unrealizedPnl: number, changePct: number, positionValue: number }`
+- `changePct` — the PnL change as a percentage of total position value (not % of PnL itself)
+
+**When to use:**
+- Risk alerts for large PnL swings
+- Auto-close or reduce positions on sudden adverse moves
+- Escalating alerts to the user via `api.publish()`
+
+**Example:**
+```typescript
+api.on('pnl_threshold', async ({ coin, unrealizedPnl, changePct }) => {
+  if (unrealizedPnl < 0) {
+    await api.publish(
+      `⚠️ ${coin} PnL dropped sharply: $${unrealizedPnl.toFixed(2)} (${changePct.toFixed(1)}% of position)`,
+      { name: 'pnl-alert' },
+    );
+  }
+});
+```
+
+#### `margin_warning` — High margin usage
+Fires when margin usage exceeds **80%** of equity. After the first trigger, it only fires again if margin usage increases by another 5 percentage points (prevents spam). Resets when margin drops back below 80%.
+
+**Payload:** `{ marginUsedPct: number, equity: number, marginUsed: number }`
+
+**When to use:**
+- Automated risk reduction (close smallest position to free margin)
+- Alerting the user before liquidation risk
+- Pausing new entries when margin is high
+
+**Example:**
+```typescript
+api.on('margin_warning', async ({ marginUsedPct, equity }) => {
+  await api.publish(
+    `🚨 Margin at ${marginUsedPct.toFixed(1)}% — equity: $${equity.toFixed(2)}. Consider reducing exposure.`,
+    { name: 'margin-alert' },
+  );
+});
+```
+
+### Choosing the Right Event — Quick Guide
+
+| Use case | Best event | Why |
+|----------|-----------|-----|
+| Alert when price crosses a fixed level | `tick` | Fires every poll — no minimum change threshold |
+| React to price momentum/volatility | `price_change` | Provides relative change data between polls |
+| Funding rate strategy | `funding_update` | Gives annualized rate directly |
+| Auto TP/SL on new positions | `position_opened` | Fires exactly when a new position appears |
+| Log when positions close | `position_closed` | Fires when position disappears |
+| Track position scaling | `position_changed` | Fires on size changes only |
+| Risk management — PnL spikes | `pnl_threshold` | Only fires on large moves (≥5% of position value) |
+| Risk management — margin | `margin_warning` | Fires at 80%+ margin usage |
+| Periodic task (DCA, rebalance) | `api.every(ms, fn)` | Better than tick for longer intervals |
+
 ### Client Methods Available
 
 The `api.client` object exposes the full Hyperliquid SDK:
@@ -652,6 +847,47 @@ export default function(api) {
 }
 ```
 
+### 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:**
@@ -680,9 +916,11 @@ openbroker auto status                      # Show running 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
 

package/openclaw.plugin.json

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

package/package.json

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

package/scripts/auto/cli.ts

@@ -2,7 +2,8 @@
 
 import { parseArgs } from '../core/utils.js';
 import { resolveScriptPath, listAutomations, ensureAutomationsDir } from './loader.js';
-import { startAutomation, getRunningAutomations } from './runtime.js';
+import { startAutomation, getRunningAutomations, getRegisteredAutomations } from './runtime.js';
+import { unregisterAutomation, cleanRegistry } from './registry.js';
 
 function printUsage() {
   console.log(`
@@ -10,8 +11,10 @@ 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)
@@ -100,24 +103,82 @@ function listCommand() {
 }
 
 function statusCommand() {
-  const running = getRunningAutomations();
+  // Show in-process automations (if any running in this process)
+  const inProcess = getRunningAutomations();
 
-  if (running.length === 0) {
+  // 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;
   }
 
-  console.log('Running automations:\n');
-  for (const a of running) {
-    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 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() {
@@ -153,12 +214,18 @@ async function main() {
     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');

package/scripts/auto/registry.ts

@@ -0,0 +1,118 @@
+// File-based automation registry — tracks desired state across processes
+// Persisted at ~/.openbroker/state/_registry.json so both CLI and plugin
+// can see which automations should be running.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+const STATE_DIR = path.join(os.homedir(), '.openbroker', 'state');
+const REGISTRY_FILE = path.join(STATE_DIR, '_registry.json');
+
+export interface RegistryEntry {
+  id: string;
+  scriptPath: string;
+  dryRun: boolean;
+  verbose: boolean;
+  pollIntervalMs: number;
+  startedAt: string;        // ISO timestamp
+  pid: number;              // Process that started it
+  status: 'running' | 'stopped' | 'error';
+  error?: string;           // Last error message if status is 'error'
+}
+
+function ensureDir(): void {
+  mkdirSync(STATE_DIR, { recursive: true });
+}
+
+function readRegistry(): RegistryEntry[] {
+  if (!existsSync(REGISTRY_FILE)) return [];
+  try {
+    const raw = readFileSync(REGISTRY_FILE, 'utf-8');
+    const entries = JSON.parse(raw);
+    return Array.isArray(entries) ? entries : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeRegistry(entries: RegistryEntry[]): void {
+  ensureDir();
+  writeFileSync(REGISTRY_FILE, JSON.stringify(entries, null, 2));
+}
+
+/** Check if a process is still alive */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // Signal 0 = just check, don't kill
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Register an automation as running */
+export function registerAutomation(entry: Omit<RegistryEntry, 'status' | 'pid' | 'startedAt'>): void {
+  const entries = readRegistry();
+
+  // Remove any existing entry with the same id
+  const filtered = entries.filter(e => e.id !== entry.id);
+
+  filtered.push({
+    ...entry,
+    status: 'running',
+    pid: process.pid,
+    startedAt: new Date().toISOString(),
+  });
+
+  writeRegistry(filtered);
+}
+
+/** Unregister an automation (remove from desired state) */
+export function unregisterAutomation(id: string): void {
+  const entries = readRegistry();
+  writeRegistry(entries.filter(e => e.id !== id));
+}
+
+/** Mark an automation as errored (keep in registry for visibility) */
+export function markAutomationError(id: string, error: string): void {
+  const entries = readRegistry();
+  const entry = entries.find(e => e.id === id);
+  if (entry) {
+    entry.status = 'error';
+    entry.error = error;
+    writeRegistry(entries);
+  }
+}
+
+/** Get all registered automations, with stale process detection */
+export function getRegisteredAutomations(): RegistryEntry[] {
+  const entries = readRegistry();
+  let dirty = false;
+
+  for (const entry of entries) {
+    if (entry.status === 'running' && !isProcessAlive(entry.pid)) {
+      // Process died without cleanup — mark as stopped
+      entry.status = 'stopped';
+      dirty = true;
+    }
+  }
+
+  if (dirty) writeRegistry(entries);
+  return entries;
+}
+
+/** Get automations that should be restarted (were running when process died) */
+export function getAutomationsToRestart(): RegistryEntry[] {
+  const entries = getRegisteredAutomations();
+  // Return entries that were running but whose process is no longer alive
+  // (getRegisteredAutomations already marked them as 'stopped')
+  // We want entries that are 'stopped' — they need to be restarted
+  return entries.filter(e => e.status === 'stopped');
+}
+
+/** Clean up the registry — remove stopped/errored entries */
+export function cleanRegistry(): void {
+  const entries = readRegistry();
+  writeRegistry(entries.filter(e => e.status === 'running' && isProcessAlive(e.pid)));
+}

package/scripts/auto/runtime.ts

@@ -11,12 +11,14 @@ import {
 } from '../core/utils.js';
 import { AutomationEventBus } from './events.js';
 import { loadAutomation } from './loader.js';
+import { registerAutomation, unregisterAutomation, markAutomationError, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
 import type {
   AutomationAPI,
   AutomationLogger,
   AutomationState,
   AutomationSnapshot,
   PositionSnapshot,
+  PublishOptions,
   ScheduledTask,
   RunningAutomation,
 } from './types.js';
@@ -167,6 +169,56 @@ async function buildSnapshot(
   };
 }
 
+// ── Publish (webhook) ───────────────────────────────────────────────
+
+function createPublish(
+  automationId: string,
+  log: AutomationLogger,
+  gatewayPort?: number,
+  hooksToken?: string,
+): (message: string, options?: PublishOptions) => Promise<boolean> {
+  return async (message: string, options?: PublishOptions): Promise<boolean> => {
+    const token = hooksToken || process.env.OPENCLAW_HOOKS_TOKEN;
+    const port = gatewayPort || parseInt(process.env.OPENCLAW_GATEWAY_PORT || '18789', 10);
+
+    if (!token) {
+      log.debug('publish() skipped — no hooks token configured (set OPENCLAW_HOOKS_TOKEN or pass hooksToken in plugin config)');
+      return false;
+    }
+
+    const body: Record<string, unknown> = {
+      message,
+      name: options?.name || `ob-auto-${automationId}`,
+      wakeMode: options?.wakeMode || 'now',
+    };
+
+    if (options?.deliver !== undefined) body.deliver = options.deliver;
+    if (options?.channel) body.channel = options.channel;
+
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (!res.ok) {
+        log.warn(`publish() failed: HTTP ${res.status} ${res.statusText}`);
+        return false;
+      }
+
+      log.debug(`publish() delivered to /hooks/agent (${message.length} chars)`);
+      return true;
+    } catch (err) {
+      log.warn(`publish() error: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }
+  };
+}
+
 // ── Runtime ─────────────────────────────────────────────────────────
 
 export interface RuntimeOptions {
@@ -175,6 +227,10 @@ export interface RuntimeOptions {
   dryRun?: boolean;
   verbose?: boolean;
   pollIntervalMs?: number;
+  /** Gateway port for webhook delivery. Falls back to OPENCLAW_GATEWAY_PORT or 18789 */
+  gatewayPort?: number;
+  /** Hooks token for webhook auth. Falls back to OPENCLAW_HOOKS_TOKEN */
+  hooksToken?: string;
 }
 
 /** Registry of all running automations */
@@ -188,12 +244,17 @@ export function getAutomation(id: string): RunningAutomation | undefined {
   return registry.get(id);
 }
 
+/** Get all automations from file-based registry (cross-process visibility) */
+export { getRegisteredFromFile as getRegisteredAutomations };
+
 export async function startAutomation(options: RuntimeOptions): Promise<RunningAutomation> {
   const {
     scriptPath,
     dryRun = false,
     verbose = false,
     pollIntervalMs = 10_000,
+    gatewayPort,
+    hooksToken,
   } = options;
 
   const id = options.id || path.basename(scriptPath, '.ts');
@@ -215,6 +276,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
   const scheduledTasks: ScheduledTask[] = [];
 
   // Build the API object
+  const publish = createPublish(id, log, gatewayPort, hooksToken);
   const api: AutomationAPI = {
     client,
     utils: { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate },
@@ -223,6 +285,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
     onStart: (handler) => startHooks.push(handler),
     onStop: (handler) => stopHooks.push(handler),
     onError: (handler) => errorHooks.push(handler),
+    publish,
     state,
     log,
     id,
@@ -278,7 +341,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
             const oldPrice = previousSnapshot.prices.get(coin);
             if (oldPrice === undefined || oldPrice === 0) continue;
             const changePct = ((newPrice - oldPrice) / oldPrice) * 100;
-            if (Math.abs(changePct) >= 0.1) { // 0.1% minimum to fire
+            if (Math.abs(changePct) >= 0.01) { // 0.01% minimum to fire (filters rounding noise)
               const errors = await eventBus.emit('price_change', { coin, oldPrice, newPrice, changePct });
               if (errors.length) await handleErrors(errors);
               eventsEmitted++;
@@ -416,7 +479,7 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
   await poll();
 
   // Stop function
-  async function stop() {
+  async function stop(opts?: { persist?: boolean }) {
     if (stopped) return;
     stopped = true;
     clearInterval(timer);
@@ -429,6 +492,12 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
 
     eventBus.removeAll();
     registry.delete(id);
+
+    // persist defaults to true — fully remove from file registry.
+    // When false (gateway shutdown), keep the entry so it restarts next time.
+    if (opts?.persist !== false) {
+      unregisterAutomation(id);
+    }
     log.info(`Stopped (${pollCount} polls, ${eventsEmitted} events)`);
   }
 
@@ -443,5 +512,15 @@ export async function startAutomation(options: RuntimeOptions): Promise<RunningA
   };
 
   registry.set(id, entry);
+
+  // Persist to file-based registry so other processes (CLI, plugin) can see it
+  registerAutomation({
+    id,
+    scriptPath,
+    dryRun,
+    verbose,
+    pollIntervalMs,
+  });
+
   return entry;
 }

package/scripts/auto/types.ts

@@ -52,6 +52,19 @@ export interface AutomationLogger {
   debug(message: string): void;
 }
 
+// ── Publish (webhook) ───────────────────────────────────────────────
+
+export interface PublishOptions {
+  /** Human-readable name for the hook (appears in logs). Default: "ob-auto-<id>" */
+  name?: string;
+  /** Wake mode: "now" triggers immediate agent turn, "next-heartbeat" queues. Default: "now" */
+  wakeMode?: 'now' | 'next-heartbeat';
+  /** Whether to deliver the agent response to messaging channels. Default: true */
+  deliver?: boolean;
+  /** Target channel (e.g. "slack", "telegram", "last"). Default: agent decides */
+  channel?: string;
+}
+
 // ── Core API ────────────────────────────────────────────────────────
 
 export interface AutomationAPI {
@@ -84,6 +97,17 @@ export interface AutomationAPI {
   /** Called when a handler throws. The error is already logged — use this for recovery logic. */
   onError(handler: (error: Error) => void | Promise<void>): void;
 
+  /**
+   * Publish a message to the OpenClaw agent via webhook.
+   * Sends to POST /hooks/agent on the local gateway, triggering an agent turn.
+   * The agent receives the message and can act on it (notify user, trade, etc.).
+   *
+   * @param message — The message string the agent will receive
+   * @param options — Optional: name, wakeMode, deliver, channel
+   * @returns true if delivered, false if webhook is not configured
+   */
+  publish(message: string, options?: PublishOptions): Promise<boolean>;
+
   /** Persisted key-value state (~/.openbroker/state/<id>.json) */
   state: AutomationState;
 
@@ -134,5 +158,10 @@ export interface RunningAutomation {
   pollCount: number;
   eventsEmitted: number;
   dryRun: boolean;
-  stop: () => Promise<void>;
+  /**
+   * Stop the automation.
+   * @param opts.persist If false, keep the entry in the file registry so it
+   *   restarts when the gateway comes back up. Default: true (fully remove).
+   */
+  stop: (opts?: { persist?: boolean }) => Promise<void>;
 }

package/scripts/plugin/index.ts

@@ -1,11 +1,78 @@
 // OpenClaw Plugin Entry Point for OpenBroker
 
-import type { OpenClawPluginApi, OpenBrokerPluginConfig } from './types.js';
+import type { OpenClawPluginApi, OpenBrokerPluginConfig, PluginLogger } from './types.js';
 import { applyConfigBridge } from './config-bridge.js';
 import { PositionWatcher } from './watcher.js';
 import { createTools } from './tools.js';
 import { registerCliCommands } from './cli.js';
 
+/**
+ * AutomationService — restarts automations from the file-based registry
+ * when the OpenClaw gateway starts. When the gateway process dies,
+ * automations die with it. On next start, this service reads the registry
+ * and restarts any automations that were previously running.
+ */
+function createAutomationService(logger: PluginLogger, gatewayPort?: number, hooksToken?: string) {
+  return {
+    id: 'openbroker-automations',
+
+    async start() {
+      const { getAutomationsToRestart } = await import('../auto/registry.js');
+      const entries = getAutomationsToRestart();
+
+      if (entries.length === 0) {
+        logger.debug('No automations to restart');
+        return;
+      }
+
+      logger.info(`Restarting ${entries.length} automation(s) from previous session`);
+
+      const { startAutomation } = await import('../auto/runtime.js');
+      const { resolveScriptPath } = await import('../auto/loader.js');
+
+      for (const entry of entries) {
+        try {
+          // Verify script still exists before restarting
+          const scriptPath = resolveScriptPath(entry.scriptPath);
+          await startAutomation({
+            scriptPath,
+            id: entry.id,
+            dryRun: entry.dryRun,
+            verbose: entry.verbose,
+            pollIntervalMs: entry.pollIntervalMs,
+            gatewayPort,
+            hooksToken,
+          });
+          logger.info(`Restarted automation: ${entry.id}`);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          logger.error(`Failed to restart automation "${entry.id}": ${msg}`);
+
+          // Mark as errored in registry so it doesn't retry forever
+          const { markAutomationError } = await import('../auto/registry.js');
+          markAutomationError(entry.id, msg);
+        }
+      }
+    },
+
+    async stop() {
+      // Stop all in-process automations but keep them in the file registry
+      // so they restart when the gateway comes back up
+      const { getRunningAutomations } = await import('../auto/runtime.js');
+      const running = getRunningAutomations();
+
+      for (const auto of running) {
+        try {
+          await auto.stop({ persist: false }); // Keep in registry for restart
+          logger.info(`Stopped automation for gateway shutdown: ${auto.id}`);
+        } catch (err) {
+          logger.error(`Error stopping automation "${auto.id}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    },
+  };
+}
+
 export default {
   id: 'openbroker',
   name: 'OpenBroker — Hyperliquid Trading',
@@ -43,14 +110,23 @@ export default {
       logger.debug('OpenBroker position watcher disabled by config');
     }
 
-    // 3. Register agent tools
-    const tools = createTools(watcher);
+    // 3. Register automation restart service
+    const resolvedHooksToken = pluginConfig.hooksToken || process.env.OPENCLAW_HOOKS_TOKEN;
+    api.registerService(createAutomationService(logger, gatewayPort, resolvedHooksToken));
+    logger.debug('OpenBroker automation service registered');
+
+    // 4. Register agent tools
+    const tools = createTools({
+      watcher,
+      gatewayPort,
+      hooksToken: pluginConfig.hooksToken || process.env.OPENCLAW_HOOKS_TOKEN,
+    });
     for (const tool of tools) {
       api.registerTool(tool);
     }
     logger.debug(`Registered ${tools.length} OpenBroker agent tools`);
 
-    // 4. Register CLI commands
+    // 5. Register CLI commands
     registerCliCommands(api, watcher, logger);
     logger.debug('OpenBroker CLI commands registered');
   },

package/scripts/plugin/tools.ts

@@ -18,7 +18,18 @@ function error(message: string) {
   return json({ error: message });
 }
 
-export function createTools(watcher: PositionWatcher | null): PluginTool[] {
+export interface ToolsContext {
+  watcher: PositionWatcher | null;
+  gatewayPort?: number;
+  hooksToken?: string;
+}
+
+export function createTools(watcherOrCtx: PositionWatcher | null | ToolsContext): PluginTool[] {
+  // Support both old signature (watcher only) and new (full context)
+  const ctx: ToolsContext = watcherOrCtx !== null && typeof watcherOrCtx === 'object' && 'watcher' in watcherOrCtx
+    ? watcherOrCtx
+    : { watcher: watcherOrCtx };
+  const { watcher, gatewayPort, hooksToken } = ctx;
   return [
     // ── Info Tools ──────────────────────────────────────────────
 
@@ -1326,6 +1337,8 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
             id: params.id ? String(params.id) : undefined,
             dryRun: params.dry === true,
             pollIntervalMs: params.poll ? Number(params.poll) : 10_000,
+            gatewayPort,
+            hooksToken,
           });
 
           return json({
@@ -1367,23 +1380,41 @@ export function createTools(watcher: PositionWatcher | null): PluginTool[] {
 
     {
       name: 'ob_auto_list',
-      description: 'List available automation scripts and running automations',
+      description: 'List available automation scripts and running automations (including those started from other processes)',
       parameters: { type: 'object', properties: {} },
       async execute() {
         const { listAutomations } = await import('../auto/loader.js');
-        const { getRunningAutomations } = await import('../auto/runtime.js');
+        const { getRunningAutomations, getRegisteredAutomations } = await import('../auto/runtime.js');
 
         const available = listAutomations();
-        const running = getRunningAutomations().map(a => ({
+
+        // In-process automations with live stats
+        const inProcess = getRunningAutomations().map(a => ({
           id: a.id,
           scriptPath: a.scriptPath,
           uptime: Math.round((Date.now() - a.startedAt.getTime()) / 1000),
           pollCount: a.pollCount,
           eventsEmitted: a.eventsEmitted,
           dryRun: a.dryRun,
+          source: 'this_process',
         }));
 
-        return json({ available, running });
+        // File-registry entries from other processes
+        const registered = getRegisteredAutomations();
+        const external = registered
+          .filter(r => !inProcess.some(ip => ip.id === r.id))
+          .map(r => ({
+            id: r.id,
+            scriptPath: r.scriptPath,
+            status: r.status,
+            pid: r.pid,
+            startedAt: r.startedAt,
+            dryRun: r.dryRun,
+            error: r.error,
+            source: 'other_process',
+          }));
+
+        return json({ available, running: [...inProcess, ...external] });
       },
     },
   ];

package/scripts/plugin/watcher.ts

@@ -284,66 +284,35 @@ export class PositionWatcher implements PluginService {
     return events;
   }
 
-  private buildHookMessage(event: PositionEvent): string {
-    const lines: string[] = [
-      `[OpenBroker Alert] ${this.formatEventHeadline(event)}`,
-      '',
-      'Details:',
-      ...Object.entries(event.details ?? {}).map(([k, v]) => `  ${k}: ${v}`),
-      '',
-      `Notify the user of this trading alert via their preferred channel.`,
-    ];
-    return lines.join('\n');
-  }
-
-  private formatEventHeadline(event: PositionEvent): string {
-    switch (event.type) {
-      case 'position_opened':
-        return `New ${event.details?.side ?? ''} position opened on ${event.coin}: ${Math.abs(parseFloat(String(event.details?.size ?? '0')))} ${event.coin} at $${event.details?.entryPrice}`;
-      case 'position_closed':
-        return `Position on ${event.coin} has been closed (was ${event.details?.previousSize} at $${event.details?.entryPrice}, last unrealized PnL: $${event.details?.lastPnl})`;
-      case 'position_size_changed':
-        return `Position on ${event.coin} size changed from ${event.details?.previousSize} to ${event.details?.newSize}`;
-      case 'pnl_threshold':
-        return `Significant PnL movement on ${event.coin}: $${Number(event.details?.previousPnl ?? 0).toFixed(2)} → $${Number(event.details?.currentPnl ?? 0).toFixed(2)} (${Number(event.details?.changePct ?? 0).toFixed(1)}% of position value)`;
-      case 'margin_warning':
-        return `Margin usage at ${Number(event.details?.marginUsedPct ?? 0).toFixed(1)}% — approaching risk threshold (equity: $${event.details?.equity}, margin used: $${event.details?.marginUsed})`;
-      default:
-        return event.message;
-    }
-  }
-
   private async sendHook(event: PositionEvent): Promise<void> {
     const port = this.gatewayPort || 18789;
 
     if (!this.hooksToken) {
-      this.logger.warn('No hooks token configured — skipping hook delivery. Set hooksToken in plugin config or OPENCLAW_HOOKS_TOKEN env var.');
+      this.logger.debug('sendHook skipped — no hooks token configured');
       return;
     }
 
-    const hookUrl = `http://127.0.0.1:${port}/hooks/agent`;
-
     try {
-      const response = await fetch(hookUrl, {
+      const res = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
           'Authorization': `Bearer ${this.hooksToken}`,
         },
         body: JSON.stringify({
-          message: this.buildHookMessage(event),
-          name: `ob-${event.type}`,
+          message: event.message,
+          name: `ob-watcher-${event.type}`,
           wakeMode: 'now',
         }),
       });
 
-      if (response.status === 202 || response.ok) {
-        this.logger.debug(`Hook delivered for ${event.type}`);
+      if (!res.ok) {
+        this.logger.warn(`sendHook failed: HTTP ${res.status} ${res.statusText}`);
       } else {
-        this.logger.warn(`Hook POST failed: ${response.status} ${response.statusText}`);
+        this.logger.debug(`sendHook delivered for ${event.type} (${event.message.length} chars)`);
       }
     } catch (err) {
-      this.logger.warn(`Hook POST error: ${err instanceof Error ? err.message : String(err)}`);
+      this.logger.warn(`sendHook error: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 }