openbroker 1.3.1 → 1.4.0

package/dist/auto/runtime.js

@@ -0,0 +1,844 @@
+// Automation Runtime — loads scripts, polls market data, dispatches events
+// Supports real-time WebSocket feeds with REST polling as fallback heartbeat
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { getClient } from '../core/client.js';
+import { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate, } from '../core/utils.js';
+import { WebSocketManager } from '../core/ws.js';
+import { AutomationEventBus } from './events.js';
+import { loadAutomation } from './loader.js';
+import { registerAutomation, unregisterAutomation, getRegisteredAutomations as getRegisteredFromFile } from './registry.js';
+import { createAutomationAudit, toSerializable } from './audit.js';
+import { startKeepAwake } from './keep-awake.js';
+// ── Observer fan-out ────────────────────────────────────────────────
+//
+// External monitoring packages (e.g. `openbroker-monitoring`) plug into
+// the audit pipeline as observers. We auto-load them via convention
+// dynamic-import: any package whose default export is a factory returning
+// an `AutomationAuditObserver` (or null) and that resolves through Node's
+// module resolver gets wired in at startup.
+const CONVENTION_OBSERVER_PACKAGES = ['openbroker-monitoring'];
+async function loadConventionObservers(log) {
+    const observers = [];
+    for (const name of CONVENTION_OBSERVER_PACKAGES) {
+        try {
+            const mod = await import(name);
+            const exported = mod.default ?? mod;
+            const observer = typeof exported === 'function' ? exported() : exported;
+            if (observer && typeof observer === 'object') {
+                observers.push(observer);
+                log.info(`[audit-observer] loaded: ${name}`);
+            }
+            else {
+                // Package resolved but its factory returned null/undefined — typically
+                // because required env (e.g. OB_DASHBOARD_URL) is missing. Surface this
+                // so operators don't silently lose telemetry.
+                log.warn(`[audit-observer] ${name} resolved but factory returned no observer — check the package's required env vars`);
+            }
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND') {
+                log.info(`[audit-observer] ${name} not installed — skipping (install it alongside openbroker to forward telemetry)`);
+            }
+            else {
+                log.warn(`[audit-observer] failed to load "${name}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    return observers;
+}
+function fanOutNote(observers, kind, payload) {
+    for (const o of observers) {
+        try {
+            o.onNote?.(kind, payload);
+        }
+        catch { /* observer must not break runtime */ }
+    }
+}
+function fanOutMetric(observers, name, value, tags) {
+    for (const o of observers) {
+        try {
+            o.onMetric?.(name, value, tags);
+        }
+        catch { /* observer must not break runtime */ }
+    }
+}
+function fanOutAgentAction(observers, action, status, details, txHash) {
+    for (const o of observers) {
+        try {
+            o.onAgentAction?.(action, status, details, txHash);
+        }
+        catch { /* observer must not break runtime */ }
+    }
+}
+const STATE_DIR = path.join(os.homedir(), '.openbroker', 'state');
+const AUDITED_WRITE_METHODS = new Set([
+    'order', 'marketOrder', 'limitOrder', 'triggerOrder',
+    'takeProfit', 'stopLoss', 'cancel', 'cancelAll',
+    'spotOrder', 'spotMarketOrder', 'spotLimitOrder', 'spotCancel',
+    'updateLeverage', 'approveBuilderFee', 'twapOrder', 'twapCancel',
+]);
+function createState(id) {
+    mkdirSync(STATE_DIR, { recursive: true });
+    const stateFile = path.join(STATE_DIR, `${id}.json`);
+    let data = {};
+    let audit = null;
+    if (existsSync(stateFile)) {
+        try {
+            data = JSON.parse(readFileSync(stateFile, 'utf-8'));
+        }
+        catch {
+            data = {};
+        }
+    }
+    let flushTimer = null;
+    function scheduleFlush() {
+        if (flushTimer)
+            return;
+        flushTimer = setTimeout(() => {
+            flushTimer = null;
+            writeFileSync(stateFile, JSON.stringify(data, null, 2));
+        }, 500);
+    }
+    return {
+        state: {
+            get(key, defaultValue) {
+                return (key in data ? data[key] : defaultValue);
+            },
+            set(key, value) {
+                data[key] = value;
+                audit?.recordStateChange('set', key, value);
+                scheduleFlush();
+            },
+            delete(key) {
+                const previous = key in data ? data[key] : undefined;
+                delete data[key];
+                audit?.recordStateChange('delete', key, previous);
+                scheduleFlush();
+            },
+            clear() {
+                data = {};
+                audit?.recordStateChange('clear', null);
+                scheduleFlush();
+            },
+        },
+        snapshot() {
+            return toSerializable(data);
+        },
+        attachAudit(nextAudit) {
+            audit = nextAudit;
+        },
+    };
+}
+// ── Logger ──────────────────────────────────────────────────────────
+function createLogger(id, verbose, audit) {
+    const prefix = `[auto:${id}]`;
+    return {
+        info: (msg) => {
+            audit?.recordLog('info', msg);
+            console.log(`${prefix} ${msg}`);
+        },
+        warn: (msg) => {
+            audit?.recordLog('warn', msg);
+            console.log(`${prefix} ⚠ ${msg}`);
+        },
+        error: (msg) => {
+            audit?.recordLog('error', msg);
+            console.error(`${prefix} ✗ ${msg}`);
+        },
+        debug: (msg) => {
+            if (verbose) {
+                audit?.recordLog('debug', msg);
+                console.log(`${prefix} … ${msg}`);
+            }
+        },
+    };
+}
+// ── Dry-run client proxy ────────────────────────────────────────────
+const WRITE_METHODS = new Set([
+    'order', 'marketOrder', 'limitOrder', 'triggerOrder',
+    'takeProfit', 'stopLoss', 'cancel', 'cancelAll',
+    'updateLeverage', 'approveBuilderFee',
+    'spotOrder', 'spotMarketOrder', 'spotLimitOrder', 'spotCancel',
+    'twapOrder', 'twapCancel',
+]);
+function createDryClient(client, log) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof prop === 'string' && WRITE_METHODS.has(prop) && typeof value === 'function') {
+                return (...args) => {
+                    log.info(`[DRY] ${prop}(${args.map(a => JSON.stringify(a)).join(', ')})`);
+                    return Promise.resolve({ status: 'ok', response: { type: 'dry_run' } });
+                };
+            }
+            return value;
+        },
+    });
+}
+function createAuditedClient(client, audit, dryRun, observers) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof prop === 'string' && AUDITED_WRITE_METHODS.has(prop) && typeof value === 'function') {
+                return async (...args) => {
+                    const actionId = `${prop}:${Date.now()}:${Math.random().toString(16).slice(2)}`;
+                    audit.recordAction({
+                        actionId,
+                        phase: 'request',
+                        method: prop,
+                        payload: { args },
+                        dryRun,
+                    });
+                    try {
+                        const result = await value.apply(target, args);
+                        audit.recordAction({
+                            actionId,
+                            phase: 'response',
+                            method: prop,
+                            result,
+                            dryRun,
+                        });
+                        fanOutAgentAction(observers, prop, 'success', { args: toSerializable(args), result: toSerializable(result), dryRun });
+                        return result;
+                    }
+                    catch (error) {
+                        audit.recordAction({
+                            actionId,
+                            phase: 'error',
+                            method: prop,
+                            error,
+                            dryRun,
+                        });
+                        fanOutAgentAction(observers, prop, 'error', { args: toSerializable(args), error: String(error), dryRun });
+                        throw error;
+                    }
+                };
+            }
+            return value;
+        },
+    });
+}
+// ── Snapshot building ───────────────────────────────────────────────
+async function buildSnapshot(client) {
+    // `metaAndAssetCtxs` contains both mostly-static market metadata and live
+    // funding/premium values. The client caches it for market lookups, so clear
+    // it before each automation poll snapshot or funding_update events freeze at
+    // the first fetched value.
+    client.invalidateMetaCache();
+    const [state, mids, metaCtxs] = await Promise.all([
+        client.getUserStateAll(),
+        client.getAllMids(),
+        client.getMetaAndAssetCtxs(),
+    ]);
+    const prices = new Map();
+    for (const [coin, mid] of Object.entries(mids)) {
+        prices.set(coin, parseFloat(mid));
+    }
+    const positions = new Map();
+    for (const ap of state.assetPositions) {
+        const p = ap.position;
+        const size = parseFloat(p.szi);
+        if (size === 0)
+            continue;
+        positions.set(p.coin, {
+            coin: p.coin,
+            size,
+            entryPrice: parseFloat(p.entryPx),
+            positionValue: parseFloat(p.positionValue),
+            unrealizedPnl: parseFloat(p.unrealizedPnl),
+            liquidationPx: p.liquidationPx ? parseFloat(p.liquidationPx) : null,
+            leverage: typeof p.leverage === 'object' ? p.leverage.value : parseFloat(String(p.leverage)),
+            marginUsed: parseFloat(p.marginUsed),
+        });
+    }
+    const equity = parseFloat(state.marginSummary.accountValue);
+    const marginUsed = parseFloat(state.marginSummary.totalMarginUsed);
+    // Build funding rates from asset contexts
+    const fundingRates = new Map();
+    const addFundingRates = (universe, assetCtxs) => {
+        if (!universe || !assetCtxs)
+            return;
+        for (let i = 0; i < universe.length; i++) {
+            const meta = universe[i];
+            const ctx = assetCtxs[i];
+            if (ctx && meta?.name) {
+                fundingRates.set(meta.name, {
+                    rate: parseFloat(String(ctx.funding || '0')),
+                    premium: parseFloat(String(ctx.premium || '0')),
+                });
+            }
+        }
+    };
+    if (metaCtxs && Array.isArray(metaCtxs)) {
+        for (const group of metaCtxs) {
+            addFundingRates(group.universe, group.assetCtxs);
+        }
+    }
+    else if (metaCtxs) {
+        addFundingRates(metaCtxs.meta?.universe, metaCtxs.assetCtxs);
+    }
+    return {
+        prices,
+        positions,
+        openOrderIds: new Set(), // filled by separate call if needed
+        equity,
+        marginUsed,
+        marginUsedPct: equity > 0 ? (marginUsed / equity) * 100 : 0,
+        fundingRates,
+        timestamp: Date.now(),
+    };
+}
+// ── Publish (webhook) ───────────────────────────────────────────────
+function createPublish(automationId, log, gatewayPort, hooksToken) {
+    return async (message, options) => {
+        const token = hooksToken;
+        const port = gatewayPort || 18789;
+        if (!token) {
+            log.debug('publish() skipped — no hooks token configured (pass --hooks-token, set OPENCLAW_HOOKS_TOKEN before invoking the CLI, or configure plugin.hooksToken)');
+            return false;
+        }
+        const body = {
+            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;
+        }
+    };
+}
+function createAuditedPublish(publish, audit) {
+    return async (message, options) => {
+        try {
+            const delivered = await publish(message, options);
+            audit.recordPublish(message, options, delivered);
+            return delivered;
+        }
+        catch (error) {
+            audit.recordError('publish', error);
+            throw error;
+        }
+    };
+}
+/** Registry of all running automations */
+const registry = new Map();
+export function getRunningAutomations() {
+    return [...registry.values()];
+}
+export function getAutomation(id) {
+    return registry.get(id);
+}
+/** Get all automations from file-based registry (cross-process visibility) */
+export { getRegisteredFromFile as getRegisteredAutomations };
+export async function startAutomation(options) {
+    const { scriptPath, dryRun = false, verbose = false, gatewayPort, hooksToken, initialState, useWebSocket = true, } = options;
+    // When WebSocket is enabled, REST poll becomes a heartbeat (30s default)
+    // When disabled, use the original 10s polling interval
+    const pollIntervalMs = options.pollIntervalMs ?? (useWebSocket ? 30_000 : 10_000);
+    const id = options.id || path.basename(scriptPath, '.ts');
+    if (registry.has(id)) {
+        throw new Error(`Automation "${id}" is already running`);
+    }
+    const stateController = createState(id);
+    // Apply --set flags before the factory function runs so CLI overrides win over persisted state.
+    if (initialState) {
+        for (const [key, value] of Object.entries(initialState)) {
+            stateController.state.set(key, value);
+        }
+    }
+    const eventBus = new AutomationEventBus();
+    const rawClient = getClient();
+    const audit = createAutomationAudit({
+        automationId: id,
+        scriptPath,
+        dryRun,
+        verbose,
+        pollIntervalMs,
+        useWebSocket,
+        accountAddress: rawClient.address,
+        walletAddress: rawClient.walletAddress,
+        isApiWallet: rawClient.isApiWallet,
+        initialState,
+        persistedState: stateController.snapshot(),
+    });
+    stateController.attachAudit(audit);
+    const log = createLogger(id, verbose, audit);
+    const keepAwakeEnabled = options.keepAwake ?? !dryRun;
+    let keepAwake = null;
+    if (keepAwakeEnabled) {
+        keepAwake = startKeepAwake(`OpenBroker automation ${id} is running`, log);
+        if (keepAwake) {
+            log.info(`keep-awake enabled via ${keepAwake.backend}.`);
+        }
+    }
+    const observers = await loadConventionObservers(log);
+    const baseClient = dryRun ? createDryClient(rawClient, log) : rawClient;
+    const client = createAuditedClient(baseClient, audit, dryRun, observers);
+    const startHooks = [];
+    const stopHooks = [];
+    const errorHooks = [];
+    const scheduledTasks = [];
+    // Build the API object
+    const publish = createAuditedPublish(createPublish(id, log, gatewayPort, hooksToken), audit);
+    const auditApi = {
+        record: (kind, payload) => {
+            audit.recordNote(kind, payload);
+            fanOutNote(observers, kind, payload);
+        },
+        metric: (name, value, tags) => {
+            audit.recordMetric(name, value, tags);
+            fanOutMetric(observers, name, value, tags);
+        },
+    };
+    const api = {
+        client,
+        utils: { roundPrice, roundSize, sleep, normalizeCoin, formatUsd, formatPercent, annualizeFundingRate },
+        on: (event, handler) => eventBus.on(event, handler),
+        every: (intervalMs, handler) => scheduledTasks.push({ intervalMs, handler, lastRun: 0 }),
+        onStart: (handler) => startHooks.push(handler),
+        onStop: (handler) => stopHooks.push(handler),
+        onError: (handler) => errorHooks.push(handler),
+        publish,
+        state: stateController.state,
+        log,
+        audit: auditApi,
+        id,
+        dryRun,
+    };
+    try {
+        // Load and execute the factory function (registers handlers)
+        log.info(`Loading automation: ${scriptPath}`);
+        const factory = await loadAutomation(scriptPath);
+        await factory(api);
+        // Call onStart hooks
+        for (const hook of startHooks) {
+            try {
+                await hook();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                audit.recordError('onStart', error);
+                log.error(`onStart hook error: ${error.message}`);
+            }
+        }
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        audit.recordError('startup', error);
+        await audit.stop({
+            status: 'error',
+            stopReason: 'startup_error',
+            pollCount: 0,
+            eventsEmitted: 0,
+        });
+        keepAwake?.stop();
+        throw error;
+    }
+    // Polling state (declared early so WebSocket handlers can reference)
+    let previousSnapshot = null;
+    let pollCount = 0;
+    let eventsEmitted = 0;
+    let isPolling = false;
+    let stopped = false;
+    async function handleErrors(errors) {
+        for (const err of errors) {
+            audit.recordError('handler', err);
+            log.error(`Handler error: ${err.message}`);
+            for (const hook of errorHooks) {
+                try {
+                    await hook(err);
+                }
+                catch { /* swallow */ }
+            }
+        }
+    }
+    function shouldPersistEvent(event) {
+        return event !== 'tick' && event !== 'price_change';
+    }
+    async function emitAutomationEvent(event, payload, source) {
+        if (shouldPersistEvent(event)) {
+            audit.recordEvent(event, source, payload);
+        }
+        const errors = await eventBus.emit(event, payload);
+        if (errors.length)
+            await handleErrors(errors);
+        eventsEmitted++;
+    }
+    // ── WebSocket setup ─────────────────────────────────────────────
+    let ws = null;
+    let wsConnected = false;
+    // Track latest prices from WebSocket for real-time price_change events
+    let wsPrices = new Map();
+    if (useWebSocket) {
+        try {
+            ws = new WebSocketManager(verbose);
+            // Wire WebSocket events to the automation event bus
+            ws.on('allMids', ({ mids }) => {
+                const now = Date.now();
+                for (const [coin, mid] of Object.entries(mids)) {
+                    const newPrice = parseFloat(mid);
+                    if (isNaN(newPrice) || newPrice === 0)
+                        continue;
+                    const oldPrice = wsPrices.get(coin);
+                    wsPrices.set(coin, newPrice);
+                    if (oldPrice !== undefined && oldPrice !== 0 && eventBus.has('price_change')) {
+                        const changePct = ((newPrice - oldPrice) / oldPrice) * 100;
+                        if (Math.abs(changePct) >= 0.01) {
+                            void emitAutomationEvent('price_change', { coin, oldPrice, newPrice, changePct }, 'ws');
+                        }
+                    }
+                }
+            });
+            ws.on('orderUpdate', (update) => {
+                audit.recordOrderUpdate({
+                    coin: update.order.coin,
+                    oid: update.order.oid,
+                    side: update.order.side === 'B' ? 'buy' : 'sell',
+                    size: parseFloat(update.order.sz),
+                    price: parseFloat(update.order.limitPx),
+                    origSize: parseFloat(update.order.origSz),
+                    status: update.status,
+                    statusTimestamp: update.statusTimestamp,
+                    raw: update,
+                });
+                if (eventBus.has('order_update')) {
+                    void emitAutomationEvent('order_update', {
+                        coin: update.order.coin,
+                        oid: update.order.oid,
+                        side: update.order.side === 'B' ? 'buy' : 'sell',
+                        size: parseFloat(update.order.sz),
+                        price: parseFloat(update.order.limitPx),
+                        origSize: parseFloat(update.order.origSz),
+                        status: update.status,
+                        statusTimestamp: update.statusTimestamp,
+                    }, 'ws');
+                }
+                // NOTE: order_filled is emitted from the userFill handler below, not from
+                // here. The previous implementation fired it from orderUpdate.status
+                // === 'filled' using update.order.sz as the size, but that field is the
+                // REMAINING size (0 on a terminal fill), not the fill delta — so every
+                // consumer saw size=0. Additionally, Hyperliquid does not emit
+                // orderUpdate events for pure partial fills that don't transition
+                // status, so partial fills were silently dropped entirely. Sourcing
+                // order_filled from userFill fixes both issues: sz there IS the fill
+                // delta, and the userFills stream fires on every fill (partial and
+                // terminal).
+            });
+            ws.on('userFill', (fill) => {
+                audit.recordFill({
+                    coin: fill.coin,
+                    side: fill.side === 'B' ? 'buy' : 'sell',
+                    size: fill.sz,
+                    price: fill.px,
+                    time: fill.time,
+                    closedPnl: fill.closedPnl,
+                    fee: fill.fee,
+                    oid: fill.oid,
+                    crossed: fill.crossed,
+                }, fill.time);
+                log.debug(`Fill: ${fill.side === 'B' ? 'BUY' : 'SELL'} ${fill.sz} ${fill.coin} @ ${fill.px} (PnL: ${fill.closedPnl})`);
+                // Emit order_filled with the authoritative fill delta + fee/pnl from
+                // the userFills WS stream. Covers both partial and terminal fills.
+                // Fee is converted to USD using feeToken: for non-USDC fees (spot
+                // buys pay in the received asset), fee × price yields USD since the
+                // fee token is the base of the traded pair and `price` is quote/base.
+                if (eventBus.has('order_filled')) {
+                    const size = parseFloat(fill.sz);
+                    const price = parseFloat(fill.px);
+                    const rawFee = parseFloat(fill.fee);
+                    const closedPnl = parseFloat(fill.closedPnl);
+                    const feeToken = fill.feeToken;
+                    let feeUsd;
+                    if (Number.isFinite(rawFee)) {
+                        if (feeToken === 'USDC' || !feeToken) {
+                            feeUsd = rawFee;
+                        }
+                        else if (Number.isFinite(price) && price > 0) {
+                            feeUsd = rawFee * price;
+                        }
+                        else {
+                            feeUsd = undefined;
+                        }
+                    }
+                    void emitAutomationEvent('order_filled', {
+                        coin: fill.coin,
+                        oid: fill.oid,
+                        side: fill.side === 'B' ? 'buy' : 'sell',
+                        size,
+                        price,
+                        fee: feeUsd,
+                        feeToken,
+                        closedPnl: Number.isFinite(closedPnl) ? closedPnl : undefined,
+                        crossed: fill.crossed,
+                    }, 'ws');
+                }
+            });
+            ws.on('userEvent', (event) => {
+                audit.recordUserEvent(event);
+                // Handle liquidation events — only available through WebSocket
+                if ('liquidation' in event && eventBus.has('liquidation')) {
+                    const liq = event.liquidation;
+                    void emitAutomationEvent('liquidation', {
+                        lid: liq.lid,
+                        liquidator: liq.liquidator,
+                        liquidatedUser: liq.liquidated_user,
+                        liquidatedNtlPos: parseFloat(liq.liquidated_ntl_pos),
+                        liquidatedAccountValue: parseFloat(liq.liquidated_account_value),
+                    }, 'ws');
+                }
+            });
+            ws.on('error', ({ error }) => {
+                audit.recordError('websocket', error);
+                log.warn(`WebSocket error: ${error.message}`);
+            });
+            ws.on('disconnected', () => {
+                wsConnected = false;
+                log.warn('WebSocket disconnected — falling back to REST polling');
+            });
+            ws.on('connected', () => {
+                wsConnected = true;
+                log.info('WebSocket connected — real-time events active');
+            });
+            // Connect and subscribe
+            const userAddress = rawClient.address;
+            await ws.subscribeAll(userAddress);
+            log.info('WebSocket subscriptions active (allMids, orderUpdates, userFills, userEvents)');
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            audit.recordError('websocket_setup', error);
+            if (verbose && error.stack) {
+                log.debug(`WebSocket setup stack: ${error.stack}`);
+            }
+            log.warn(`WebSocket setup failed: ${error.message} — using REST polling only`);
+            ws = null;
+            wsConnected = false;
+        }
+    }
+    async function poll() {
+        if (isPolling || stopped)
+            return;
+        isPolling = true;
+        try {
+            const snapshot = await buildSnapshot(rawClient);
+            pollCount++;
+            const now = Date.now();
+            audit.recordSnapshot({
+                pollCount,
+                equity: snapshot.equity,
+                marginUsed: snapshot.marginUsed,
+                marginUsedPct: snapshot.marginUsedPct,
+                positions: [...snapshot.positions.values()],
+                timestamp: now,
+            });
+            // Always emit tick
+            await emitAutomationEvent('tick', { timestamp: now, pollCount }, 'poll');
+            if (previousSnapshot) {
+                // Price changes (skip when WebSocket is handling real-time prices)
+                if (eventBus.has('price_change') && !wsConnected) {
+                    for (const [coin, newPrice] of snapshot.prices) {
+                        const oldPrice = previousSnapshot.prices.get(coin);
+                        if (oldPrice === undefined || oldPrice === 0)
+                            continue;
+                        const changePct = ((newPrice - oldPrice) / oldPrice) * 100;
+                        if (Math.abs(changePct) >= 0.01) { // 0.01% minimum to fire (filters rounding noise)
+                            await emitAutomationEvent('price_change', { coin, oldPrice, newPrice, changePct }, 'poll');
+                        }
+                    }
+                }
+                // Funding updates
+                if (eventBus.has('funding_update')) {
+                    for (const [coin, data] of snapshot.fundingRates) {
+                        await emitAutomationEvent('funding_update', {
+                            coin,
+                            fundingRate: data.rate,
+                            annualized: annualizeFundingRate(data.rate),
+                            premium: data.premium,
+                        }, 'poll');
+                    }
+                }
+                // Position opened
+                if (eventBus.has('position_opened')) {
+                    for (const [coin, pos] of snapshot.positions) {
+                        if (!previousSnapshot.positions.has(coin)) {
+                            await emitAutomationEvent('position_opened', {
+                                coin,
+                                side: pos.size > 0 ? 'long' : 'short',
+                                size: Math.abs(pos.size),
+                                entryPrice: pos.entryPrice,
+                            }, 'poll');
+                        }
+                    }
+                }
+                // Position closed
+                if (eventBus.has('position_closed')) {
+                    for (const [coin, prevPos] of previousSnapshot.positions) {
+                        if (!snapshot.positions.has(coin)) {
+                            await emitAutomationEvent('position_closed', {
+                                coin,
+                                previousSize: prevPos.size,
+                                entryPrice: prevPos.entryPrice,
+                            }, 'poll');
+                        }
+                    }
+                }
+                // Position size changed
+                if (eventBus.has('position_changed')) {
+                    for (const [coin, pos] of snapshot.positions) {
+                        const prevPos = previousSnapshot.positions.get(coin);
+                        if (prevPos && pos.size !== prevPos.size) {
+                            await emitAutomationEvent('position_changed', {
+                                coin,
+                                oldSize: prevPos.size,
+                                newSize: pos.size,
+                                entryPrice: pos.entryPrice,
+                            }, 'poll');
+                        }
+                    }
+                }
+                // PnL threshold (5% of position value)
+                if (eventBus.has('pnl_threshold')) {
+                    for (const [coin, pos] of snapshot.positions) {
+                        const prevPos = previousSnapshot.positions.get(coin);
+                        if (!prevPos || pos.positionValue === 0)
+                            continue;
+                        const pnlChange = Math.abs(pos.unrealizedPnl - prevPos.unrealizedPnl);
+                        const changePct = (pnlChange / pos.positionValue) * 100;
+                        if (changePct >= 5) {
+                            await emitAutomationEvent('pnl_threshold', {
+                                coin,
+                                unrealizedPnl: pos.unrealizedPnl,
+                                changePct,
+                                positionValue: pos.positionValue,
+                            }, 'poll');
+                        }
+                    }
+                }
+                // Margin warning (80%)
+                if (eventBus.has('margin_warning') && snapshot.marginUsedPct >= 80) {
+                    const prevPct = previousSnapshot.marginUsedPct;
+                    if (prevPct < 80 || snapshot.marginUsedPct - prevPct >= 5) {
+                        await emitAutomationEvent('margin_warning', {
+                            marginUsedPct: snapshot.marginUsedPct,
+                            equity: snapshot.equity,
+                            marginUsed: snapshot.marginUsed,
+                        }, 'poll');
+                    }
+                }
+                // Order filled — compare open order IDs
+                // (Skipped for MVP — requires tracking open orders per poll, will add when needed)
+            }
+            // Run scheduled tasks
+            for (const task of scheduledTasks) {
+                if (now - task.lastRun >= task.intervalMs) {
+                    try {
+                        await task.handler();
+                    }
+                    catch (err) {
+                        const error = err instanceof Error ? err : new Error(String(err));
+                        audit.recordError('scheduled_task', error);
+                        log.error(`Scheduled task error: ${error.message}`);
+                        await handleErrors([error]);
+                    }
+                    task.lastRun = now;
+                }
+            }
+            previousSnapshot = snapshot;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            audit.recordError('poll', error);
+            log.error(`Poll error: ${error.message}`);
+        }
+        finally {
+            isPolling = false;
+        }
+    }
+    // Start polling
+    const wsLabel = wsConnected ? ', ws=on' : (useWebSocket ? ', ws=failed' : '');
+    log.info(`Started (poll every ${pollIntervalMs / 1000}s, dry=${dryRun}${wsLabel})`);
+    const timer = setInterval(poll, pollIntervalMs);
+    // Initial poll to seed state
+    await poll();
+    // Stop function
+    async function stop(opts) {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(timer);
+        // Close WebSocket
+        if (ws) {
+            ws.removeAllListeners();
+            await ws.close();
+            ws = null;
+        }
+        for (const hook of stopHooks) {
+            try {
+                await hook();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                audit.recordError('onStop', error);
+                log.error(`onStop hook error: ${error.message}`);
+            }
+        }
+        keepAwake?.stop();
+        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)`);
+        await audit.stop({
+            status: 'stopped',
+            stopReason: opts?.persist === false ? 'shutdown_keep_registry' : 'manual_stop',
+            pollCount,
+            eventsEmitted,
+        });
+    }
+    const entry = {
+        id,
+        scriptPath,
+        startedAt: new Date(),
+        get pollCount() { return pollCount; },
+        get eventsEmitted() { return eventsEmitted; },
+        dryRun,
+        stop,
+    };
+    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;
+}