@reefclaw/openclaw-plugin 0.1.0

package/bridge/gateway/event-parser.js

@@ -0,0 +1,793 @@
+// Agent event parser for the OpenClaw gateway.
+// Consumes raw agent events (routed by GatewayWsClient) and transforms them
+// into ProviderEvent[] that the GatewayProvider can fire to the bridge.
+import { logger } from '../logger.js';
+const TAG = 'event-parser';
+// ---- CCXT → ReefClaw mapping functions ----
+const CCXT_STATUS_MAP = {
+    open: 'SUBMITTED',
+    closed: 'FILLED',
+    canceled: 'CANCELLED',
+    cancelled: 'CANCELLED', // CCXT has both spellings across exchanges
+    expired: 'EXPIRED',
+    rejected: 'REJECTED',
+    pending: 'PENDING',
+};
+export function mapCcxtStatus(ccxtStatus) {
+    const mapped = CCXT_STATUS_MAP[ccxtStatus];
+    if (!mapped) {
+        logger.warn(TAG, `Unmapped CCXT status: "${ccxtStatus}", using uppercase`);
+    }
+    return mapped ?? ccxtStatus.toUpperCase();
+}
+export function mapCcxtSide(ccxtSide) {
+    return ccxtSide.toLowerCase() === 'sell' ? 'SELL' : 'BUY';
+}
+export function mapCcxtType(ccxtType) {
+    return ccxtType.toLowerCase() === 'limit' ? 'LIMIT' : 'MARKET';
+}
+/**
+ * Map a CCXT order to a ReefClaw OrderData.
+ * Returns null if the order has missing critical fields.
+ */
+/**
+ * True when a CCXT order can only REDUCE/CLOSE a position (a protective bracket),
+ * never open/add. Detects ALL forms a Binance Futures stop/TP can take:
+ *   - `reduceOnly` (unified or raw info)
+ *   - `closePosition` (the position-bound form ReefClaw brackets actually use —
+ *     see plugin bracket-params.ts; a `reduceOnly`-only check would MISS these
+ *     and the kill switch would cancel them, leaving a naked position)
+ *   - a STOP / TAKE_PROFIT order type (protective by nature)
+ * The kill switch uses this to preserve protection. Errs toward `true` only on
+ * real protective signals; a plain LIMIT/MARKET entry has none → false.
+ */
+export function isProtectiveOrder(ccxt) {
+    const o = ccxt;
+    if (o.reduceOnly === true || o.info?.reduceOnly === true || o.info?.reduceOnly === 'true')
+        return true;
+    if (o.info?.closePosition === true || o.info?.closePosition === 'true')
+        return true;
+    const rawType = String(o.info?.origType ?? o.info?.type ?? o.type ?? '').toUpperCase();
+    if (rawType.includes('STOP') || rawType.includes('TAKE_PROFIT'))
+        return true;
+    return false;
+}
+export function mapCcxtOrder(ccxt) {
+    if (!ccxt.id || typeof ccxt.id !== 'string') {
+        logger.warn(TAG, `CCXT order missing valid ID: ${JSON.stringify(ccxt.id)}`);
+        return null;
+    }
+    if (!ccxt.symbol || typeof ccxt.symbol !== 'string') {
+        logger.warn(TAG, `CCXT order ${ccxt.id} missing symbol`);
+        return null;
+    }
+    if (ccxt.amount === null || ccxt.amount === undefined) {
+        logger.warn(TAG, `CCXT order ${ccxt.id} missing amount`);
+        return null;
+    }
+    const now = new Date().toISOString();
+    const ts = ccxt.datetime ?? (ccxt.timestamp ? new Date(ccxt.timestamp).toISOString() : now);
+    const protective = isProtectiveOrder(ccxt);
+    return {
+        id: ccxt.id,
+        symbol: ccxt.symbol,
+        side: mapCcxtSide(ccxt.side),
+        type: mapCcxtType(ccxt.type),
+        status: mapCcxtStatus(ccxt.status),
+        quantity: ccxt.amount,
+        filledQuantity: ccxt.filled ?? 0,
+        averageFillPrice: ccxt.average ?? 0,
+        timeInForce: (ccxt.timeInForce ?? 'GTC').toUpperCase(),
+        createdAt: ts,
+        updatedAt: ts,
+        ...(protective && { protective: true }),
+    };
+}
+/**
+ * Build a FillData from a CCXT order (when the order has fills).
+ * expectedPrice is the limit price (or average if market order).
+ */
+export function buildFillFromCcxtOrder(ccxt, expectedPrice) {
+    if (!ccxt.filled || ccxt.filled <= 0)
+        return null;
+    const fillPrice = ccxt.average ?? 0;
+    if (fillPrice <= 0) {
+        logger.warn(TAG, `Order ${ccxt.id} has fill but no average price, skipping fill data`);
+        return null;
+    }
+    const expected = expectedPrice ?? ccxt.price ?? fillPrice;
+    const slippage = fillPrice - expected;
+    const slippageBps = expected > 0 ? (slippage / expected) * 10_000 : 0;
+    const now = new Date().toISOString();
+    const ts = ccxt.datetime ?? (ccxt.timestamp ? new Date(ccxt.timestamp).toISOString() : now);
+    // CCXT exposes `reduceOnly` on the unified order shape for futures; Binance
+    // Futures also surfaces it on `info.reduceOnly`. Take the unified value
+    // when present, fall back to the raw Binance field, leave undefined when
+    // neither is set (legacy paths / non-futures venues).
+    const ccxtReduceOnly = ccxt.reduceOnly;
+    const rawInfo = ccxt.info;
+    const reduceOnly = typeof ccxtReduceOnly === 'boolean'
+        ? ccxtReduceOnly
+        : typeof rawInfo?.reduceOnly === 'boolean'
+            ? rawInfo.reduceOnly
+            : undefined;
+    return {
+        id: `fill-${ccxt.id}-${ccxt.filled}-${ccxt.timestamp ?? Date.now()}`,
+        orderId: ccxt.id,
+        symbol: ccxt.symbol,
+        side: mapCcxtSide(ccxt.side),
+        quantity: ccxt.filled,
+        price: fillPrice,
+        expectedPrice: expected,
+        slippage: +slippage.toFixed(8),
+        slippageBps: +slippageBps.toFixed(2),
+        fee: ccxt.fee?.cost ?? 0,
+        feeCurrency: ccxt.fee?.currency ?? 'USDT',
+        timestamp: ts,
+        ...(reduceOnly !== undefined && { reduceOnly }),
+    };
+}
+/**
+ * Map a CCXT order into a full OrderUpdatePayload.
+ * Returns null if the order has invalid critical fields.
+ */
+export function mapCcxtOrderToUpdate(ccxt, expectedPrice) {
+    const order = mapCcxtOrder(ccxt);
+    if (!order)
+        return null;
+    const fill = buildFillFromCcxtOrder(ccxt, expectedPrice);
+    return {
+        orderId: order.id,
+        status: order.status,
+        order,
+        ...(fill && { fill }),
+        timestamp: order.updatedAt,
+    };
+}
+/**
+ * Map a CCXT ticker to a ReefClaw TickerData.
+ * Returns null if the ticker has no valid price data.
+ */
+export function mapCcxtTicker(ccxt) {
+    if (!ccxt.symbol || typeof ccxt.symbol !== 'string') {
+        logger.warn(TAG, `CCXT ticker missing symbol`);
+        return null;
+    }
+    if (ccxt.last === null && ccxt.bid === null && ccxt.ask === null) {
+        logger.warn(TAG, `Ticker ${ccxt.symbol} has no valid prices, skipping`);
+        return null;
+    }
+    return {
+        symbol: ccxt.symbol,
+        lastPrice: ccxt.last ?? 0,
+        bidPrice: ccxt.bid ?? 0,
+        askPrice: ccxt.ask ?? 0,
+        volume24h: ccxt.baseVolume ?? 0,
+        change24h: ccxt.change ?? 0,
+        change24hPercent: ccxt.percentage ?? 0,
+        timestamp: ccxt.datetime ?? new Date().toISOString(),
+    };
+}
+/**
+ * Map a CCXT balance response to ReefClaw balance shape.
+ * Extracts the balance for a given currency (default: USDT).
+ *
+ * On Binance Futures, prefer `info.assets[]` over CCXT's per-asset
+ * `free`/`used` fields. Two reasons:
+ *
+ * 1. Under cross-margin, per-asset `used` from CCXT is structurally 0 —
+ *    margin is shared across the account, not booked against any one asset.
+ *    The plugin backfills `free=total` when `used==0`, which sets
+ *    `available` to the full wallet and hides the actual locked margin.
+ *
+ * 2. Multi-asset accounts settle realized PnL into a separate `BNFCR` line —
+ *    negative when net-loss, positive when net-gain. It's independent of the
+ *    funded stablecoin (USDT/USDC) and must be folded into both wallet and
+ *    available reads so the dashboard's `Available + Locked = NAV`-style
+ *    invariant holds rather than the figures reading off the USDC line alone.
+ *
+ * `info.assets[i].availableBalance` is Binance's authoritative
+ * available-after-margin number; `walletBalance` is the wallet-only line
+ * (excludes uPnl). We sum these across {funded stablecoin, BNFCR}; the
+ * gateway derives `Locked = NAV − Available` so the invariant holds.
+ *
+ * Falls back to the legacy per-currency / top-level shape when `info.assets`
+ * is absent (paper, non-Binance exchanges, mocks).
+ */
+export function mapCcxtBalance(ccxt, currency = 'USDT') {
+    const fromInfo = mapBinanceFromInfoAssets(ccxt, currency);
+    if (fromInfo)
+        return fromInfo;
+    // Binance USDⓈ-M Futures settles in USDT or USDC — check both and sum.
+    const currencies = currency === 'USDT' ? ['USDT', 'USDC'] : [currency];
+    // CCXT balances can be in two shapes:
+    // 1. { USDT: { free: 1000, used: 200, total: 1200 } }
+    // 2. { free: { USDT: 1000 }, used: { USDT: 200 }, total: { USDT: 1200 } }
+    // Try shape 1 first: per-currency objects
+    let totalVal = 0, availableVal = 0, lockedVal = 0;
+    let foundShape1 = false;
+    for (const cur of currencies) {
+        const perCurrency = ccxt[cur];
+        if (perCurrency && typeof perCurrency === 'object' && 'free' in perCurrency) {
+            availableVal += perCurrency.free ?? 0;
+            lockedVal += perCurrency.used ?? 0;
+            totalVal += perCurrency.total ?? 0;
+            foundShape1 = true;
+        }
+    }
+    if (!foundShape1) {
+        // Fallback: top-level free/used/total maps
+        const free = ccxt.free;
+        const used = ccxt.used;
+        const total = ccxt.total;
+        for (const cur of currencies) {
+            availableVal += free?.[cur] ?? 0;
+            lockedVal += used?.[cur] ?? 0;
+            totalVal += total?.[cur] ?? 0;
+        }
+    }
+    return { currency, available: availableVal, locked: lockedVal, total: totalVal };
+}
+/**
+ * Extract liquidation-risk fields from a CCXT position.  Reads the CCXT
+ * unified shape first (`position.liquidationPrice`, `position.leverage`,
+ * `position.maintenanceMargin`, `position.marginRatio`) and falls back to
+ * Binance's raw `info.*` shape — `info.liquidationPrice`, `info.leverage`,
+ * `info.maintMargin`, `info.marginRatio` — which arrives as stringy decimals
+ * on the futures REST endpoint.  Returns an object of optional numbers so
+ * callers can spread it directly into the outgoing position payload.
+ *
+ * Verified against:
+ *   - CCXT unified position fields (ccxt docs → "position structure")
+ *   - Binance Futures `/fapi/v2/positionRisk` response
+ *     (developers.binance.com → derivatives → positionRisk)
+ */
+export function extractLiquidationFields(pos) {
+    const info = (pos.info ?? {});
+    const num = (v) => {
+        if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+            return v;
+        if (typeof v === 'string' && v.length > 0) {
+            const parsed = parseFloat(v);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return parsed;
+        }
+        return undefined;
+    };
+    const liquidationPrice = num(pos.liquidationPrice) ?? num(info.liquidationPrice);
+    const leverage = num(pos.leverage) ?? num(info.leverage);
+    const maintenanceMargin = num(pos.maintenanceMargin) ?? num(info.maintMargin) ?? num(info.maintenanceMargin);
+    const marginRatio = num(pos.marginRatio) ?? num(info.marginRatio);
+    const out = {};
+    if (liquidationPrice !== undefined)
+        out.liquidationPrice = liquidationPrice;
+    if (leverage !== undefined)
+        out.leverage = leverage;
+    if (maintenanceMargin !== undefined)
+        out.maintenanceMargin = maintenanceMargin;
+    if (marginRatio !== undefined)
+        out.marginRatio = marginRatio;
+    return out;
+}
+/**
+ * Narrow plugin-side `pos.bracket` at the skill/snapshot boundary.
+ * The plugin attaches it via LiveAdapter.decoratePositionsWithMetadata when
+ * BracketLedger has an active/partial/attaching row for the symbol. The
+ * CcxtPosition index signature is `unknown`, so we re-validate shape here
+ * before forwarding into ReconciliationSnapshot.
+ *
+ * Returns undefined when the field is absent (paper mode, no bracket attached,
+ * terminal-state bracket) or malformed. The webapp hides bracket lines when
+ * the field is undefined.
+ */
+export function extractBracketField(pos) {
+    const raw = pos.bracket;
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    if (typeof r.state !== 'string' || r.state.length === 0)
+        return undefined;
+    const num = (v) => {
+        if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+            return v;
+        return undefined;
+    };
+    const slPrice = num(r.slPrice);
+    const tpPrice = num(r.tpPrice);
+    // A bracket row with neither leg is useless to the UI — treat as no bracket.
+    if (slPrice === undefined && tpPrice === undefined)
+        return undefined;
+    const out = { state: r.state };
+    if (slPrice !== undefined)
+        out.slPrice = slPrice;
+    if (tpPrice !== undefined)
+        out.tpPrice = tpPrice;
+    return out;
+}
+/**
+ * Build the wallet/available/locked tuple from Binance Futures `info.assets[]`
+ * when present. Returns null when the field is absent or unusable so the
+ * caller falls back to legacy per-currency reads.
+ */
+function mapBinanceFromInfoAssets(ccxt, currency) {
+    const info = ccxt.info;
+    // Prefer Binance's own account-level aggregates when present. From
+    // `/fapi/v3/account` (passed through verbatim at `info`): in Multi-Assets
+    // Mode `totalWalletBalance` is the USD-denominated wallet across all margin
+    // assets, each non-USD collateral valued at Binance's live index — the
+    // exact number the app's Futures "Wallet Balance"/"Available" show
+    // (verified vs developers.binance.com → Account Information V3,
+    // 2026-05-16). The per-asset reconstruction below sums USDC at FACE 1.0,
+    // but Binance values it at the live USDC/USD index (~0.9998), leaving the
+    // dashboard ~$0.2 permanently high ("figures slightly off always"). Keep
+    // `locked = total - available` — identical relationship to the per-asset
+    // branch, so the Available/Locked invariant is unchanged.
+    if (info && info.totalWalletBalance != null && info.availableBalance != null) {
+        const total = parseFloat(String(info.totalWalletBalance));
+        const available = parseFloat(String(info.availableBalance));
+        if (Number.isFinite(total) && Number.isFinite(available)) {
+            return { currency, total, available, locked: Math.max(0, total - available) };
+        }
+    }
+    const assets = info?.assets;
+    if (!Array.isArray(assets) || assets.length === 0)
+        return null;
+    let usdtWallet = 0, usdtAvail = 0;
+    let usdcWallet = 0, usdcAvail = 0;
+    let bnfcrWallet = 0, bnfcrAvail = 0;
+    let sawBnfcrAvail = false;
+    let sawAny = false;
+    const pickFloat = (v) => {
+        const n = parseFloat(String(v ?? 0));
+        return Number.isFinite(n) ? n : 0;
+    };
+    for (const a of assets) {
+        if (typeof a?.asset !== 'string')
+            continue;
+        if (a.asset === 'USDT') {
+            usdtWallet = pickFloat(a.walletBalance);
+            usdtAvail = pickFloat(a.availableBalance);
+            sawAny = true;
+        }
+        else if (a.asset === 'USDC') {
+            usdcWallet = pickFloat(a.walletBalance);
+            usdcAvail = pickFloat(a.availableBalance);
+            sawAny = true;
+        }
+        else if (a.asset === 'BNFCR') {
+            bnfcrWallet = pickFloat(a.walletBalance);
+            bnfcrAvail = pickFloat(a.availableBalance);
+            sawBnfcrAvail = a.availableBalance !== undefined && Number.isFinite(parseFloat(String(a.availableBalance)));
+            sawAny = true;
+        }
+    }
+    if (!sawAny)
+        return null;
+    // Funded stablecoin = whichever line has the larger wallet balance.
+    // Avoids summing USDT + USDC (cross-margin can mirror a position's notional
+    // into the non-funded line as a phantom).
+    const useUsdt = usdtWallet >= usdcWallet;
+    const wallet = (useUsdt ? usdtWallet : usdcWallet) + bnfcrWallet;
+    const bnfcrAvailableContribution = sawBnfcrAvail && bnfcrAvail !== 0 ? bnfcrAvail : bnfcrWallet;
+    const available = (useUsdt ? usdtAvail : usdcAvail) + bnfcrAvailableContribution;
+    const locked = Math.max(0, wallet - available);
+    return { currency, total: wallet, available, locked };
+}
+// ---- Tool names that produce order-related results ----
+const ORDER_TOOL_NAMES = new Set([
+    'create_order', 'ccxt_create_order',
+    'cancel_order', 'ccxt_cancel_order',
+    'cancel_all_orders', 'ccxt_cancel_all_orders',
+    'close_position', 'ccxt_close_position', 'close_all_positions',
+    'edit_order', 'ccxt_edit_order',
+]);
+const TICKER_TOOL_NAMES = new Set([
+    'fetch_ticker', 'ccxt_fetch_ticker', 'binance_fetch_ticker', 'get_ticker',
+]);
+const BALANCE_TOOL_NAMES = new Set([
+    'fetch_balance', 'ccxt_fetch_balance', 'binance_fetch_balance', 'get_balance',
+]);
+/**
+ * Check if a tool name matches a known set, handling namespaced names like
+ * "reefclaw-paper-trading:create_order" by stripping the prefix.
+ */
+function matchesToolSet(name, knownNames) {
+    if (knownNames.has(name))
+        return true;
+    const colonIdx = name.lastIndexOf(':');
+    return colonIdx >= 0 ? knownNames.has(name.substring(colonIdx + 1)) : false;
+}
+// ---- Error rate tracking ----
+const ERROR_WINDOW_MS = 3_600_000; // 1 hour rolling window
+// ---- Assistant buffer expiry ----
+const BUFFER_EXPIRY_MS = 300_000; // 5 minutes — prune abandoned runs
+/** Inactivity timeout — if no new chunks arrive for this long, auto-flush the buffer.
+ *  This handles the case where OpenClaw's lifecycle 'end' event never arrives
+ *  (e.g., the run ends without a lifecycle event).
+ *
+ *  NOTE: Set high because agents routinely interleave tool calls with text AND
+ *  models can pause for extended periods during complex reasoning (30-60s+ between
+ *  text chunks is normal for long responses). A premature flush splits the message,
+ *  potentially causing content loss when the webapp merges or replaces partial content.
+ *  The lifecycle 'end' event is the normal flush trigger — this timer is a LAST RESORT
+ *  safety net for when 'end' never fires, and should almost never trigger during
+ *  normal operation. */
+const BUFFER_INACTIVITY_MS = 120_000; // 120 seconds — matches webapp streaming timeout
+// ---- EventParser class ----
+export class EventParser {
+    /** Buffered assistant text per runId, with timestamps for expiry */
+    assistantBuffers = new Map();
+    /** Last decision timestamp (set on lifecycle 'start') */
+    lastDecisionTs = null;
+    /** Error timestamps within the rolling window */
+    errorTimestamps = [];
+    /** Symbol for balance currency extraction */
+    quoteCurrency;
+    /** Callback to emit events from inactivity timer (outside parseAgentEvent flow) */
+    onAsyncEvents;
+    constructor(quoteCurrency = 'USDT', onAsyncEvents) {
+        this.quoteCurrency = quoteCurrency;
+        this.onAsyncEvents = onAsyncEvents ?? null;
+    }
+    /**
+     * Parse a raw agent event into zero or more ProviderEvents.
+     * GatewayProvider calls this on every 'agent' event from the WS client.
+     */
+    parseAgentEvent(payload) {
+        const { stream, runId, data } = payload;
+        switch (stream) {
+            case 'lifecycle':
+                return this.handleLifecycle(runId, data);
+            case 'assistant':
+                return this.handleAssistant(runId, data);
+            case 'tool':
+                return this.handleTool(data);
+            default:
+                logger.debug(TAG, `Unknown stream type: ${stream}`);
+                return [];
+        }
+    }
+    /** Get the last decision timestamp */
+    getLastDecision() {
+        return this.lastDecisionTs;
+    }
+    /** Get the rolling error rate (errors per hour) */
+    getErrorRate() {
+        this.pruneErrorTimestamps();
+        return this.errorTimestamps.length;
+    }
+    // ---- Stream handlers ----
+    handleLifecycle(runId, data) {
+        const phase = data?.phase;
+        if (!phase) {
+            logger.debug(TAG, `Lifecycle event missing phase for run ${runId}`);
+            return [];
+        }
+        switch (phase) {
+            case 'start':
+                this.lastDecisionTs = new Date().toISOString();
+                logger.debug(TAG, `Agent turn started: ${runId}`);
+                return [];
+            case 'end': {
+                logger.debug(TAG, `Agent turn ended: ${runId}`);
+                return this.flushAssistantBuffer(runId);
+            }
+            case 'error': {
+                const errMsg = data.error ?? 'Unknown agent error';
+                logger.warn(TAG, `Agent error (run ${runId}): ${errMsg}`);
+                this.errorTimestamps.push(Date.now());
+                // Still flush the buffer — partial responses are better than nothing
+                return this.flushAssistantBuffer(runId);
+            }
+            default:
+                logger.debug(TAG, `Unknown lifecycle phase: ${phase}`);
+                return [];
+        }
+    }
+    handleAssistant(runId, data) {
+        const chunk = data?.delta ?? data?.text ?? '';
+        if (!chunk)
+            return [];
+        // Prune expired buffers on each update to prevent unbounded growth
+        this.pruneExpiredBuffers();
+        const existing = this.assistantBuffers.get(runId);
+        const isFirst = !existing;
+        // Clear any existing inactivity timer (we got a new chunk, so reset the clock)
+        if (existing?.inactivityTimer) {
+            clearTimeout(existing.inactivityTimer);
+        }
+        const newText = (existing?.text ?? '') + chunk;
+        // Set up inactivity timer — if no more chunks arrive within BUFFER_INACTIVITY_MS,
+        // auto-flush the buffer and emit chatMessageEnd. This handles cases where the
+        // OpenClaw lifecycle 'end' event never fires.
+        // If a tool call is active, skip the flush — the tool may take a while and
+        // more assistant text will likely follow when it completes.
+        const inactivityTimer = setTimeout(() => {
+            const entry = this.assistantBuffers.get(runId);
+            if (entry) {
+                if (entry.toolActive) {
+                    logger.debug(TAG, `Inactivity timeout for run ${runId} — suppressed (tool in-flight)`);
+                    // Re-arm the timer: check again after another interval
+                    entry.inactivityTimer = setTimeout(() => {
+                        const e2 = this.assistantBuffers.get(runId);
+                        if (e2 && !e2.toolActive) {
+                            logger.info(TAG, `Inactivity timeout (re-armed) for run ${runId} — flushing (${e2.text.length} chars)`);
+                            const events = this.flushAssistantBuffer(runId);
+                            if (events.length > 0 && this.onAsyncEvents) {
+                                this.onAsyncEvents(events);
+                            }
+                        }
+                    }, BUFFER_INACTIVITY_MS);
+                    return;
+                }
+                logger.info(TAG, `Inactivity timeout for run ${runId} — auto-flushing assistant buffer (${entry.text.length} chars)`);
+                const events = this.flushAssistantBuffer(runId);
+                if (events.length > 0 && this.onAsyncEvents) {
+                    this.onAsyncEvents(events);
+                }
+            }
+        }, BUFFER_INACTIVITY_MS);
+        this.assistantBuffers.set(runId, { text: newText, lastUpdate: Date.now(), inactivityTimer, toolActive: existing?.toolActive ?? false });
+        logger.debug(TAG, `Buffered ${chunk.length} chars for run ${runId} (total: ${newText.length})`);
+        const events = [];
+        const msgId = `agent-msg-${runId}`;
+        // Emit start event on first chunk so UI can create the placeholder message
+        if (isFirst) {
+            events.push({
+                event: 'chatMessageStart',
+                data: { id: msgId, runId, timestamp: new Date().toISOString() },
+            });
+        }
+        // Emit delta chunk for streaming display
+        events.push({
+            event: 'chatMessageChunk',
+            data: { id: msgId, delta: chunk },
+        });
+        return events;
+    }
+    handleTool(data) {
+        if (!data)
+            return [];
+        const toolName = data.tool ?? data.name ?? '';
+        // Track tool start — mark all active buffers as having a tool in-flight.
+        // This prevents the inactivity timer from prematurely flushing the assistant
+        // buffer while a tool call is executing (which can take 10-20s).
+        if (data.phase === 'start') {
+            const events = [];
+            for (const [runId, entry] of this.assistantBuffers) {
+                if (!entry.toolActive) {
+                    entry.toolActive = true;
+                    logger.debug(TAG, `Tool started (${toolName}) — pausing inactivity timer for run ${runId}`);
+                }
+                // Emit keep-alive so the webapp resets its streaming timeout.
+                // Without this, long tool chains (60-120s+) cause the webapp's
+                // 120s watchdog to fire and truncate the response mid-stream.
+                const msgId = `agent-msg-${runId}`;
+                events.push({
+                    event: 'chatStreamingKeepAlive',
+                    data: { id: msgId, toolName },
+                });
+            }
+            return events;
+        }
+        // Track tool end — unmark tool-active so the inactivity timer can resume.
+        // Reset the inactivity timer for each buffer so it starts fresh after the tool completes.
+        if (data.phase === 'end') {
+            this.resumeBuffersAfterTool();
+        }
+        // Only care about tool end events (with results) for data parsing
+        if (data.phase !== 'end')
+            return [];
+        if (!toolName)
+            return [];
+        const result = data.result;
+        if (result === undefined || result === null)
+            return [];
+        logger.debug(TAG, `Tool end: name="${toolName}", resultType=${typeof result}, keys=${typeof result === 'object' && result !== null ? Object.keys(result).join(',') : 'N/A'}`);
+        // Parse the result — it may be a string (double-wrapped JSON) or an object
+        let parsed = result;
+        if (typeof result === 'string') {
+            try {
+                parsed = JSON.parse(result);
+            }
+            catch {
+                logger.debug(TAG, `Tool ${toolName} result is non-JSON string, skipping`);
+                return [];
+            }
+        }
+        // Also unwrap the nested envelope if present (result.content[0].text)
+        parsed = unwrapToolEnvelope(parsed);
+        // Route based on tool name (supports namespaced names like "plugin:create_order")
+        if (matchesToolSet(toolName, ORDER_TOOL_NAMES)) {
+            return this.parseOrderResult(toolName, parsed);
+        }
+        if (matchesToolSet(toolName, TICKER_TOOL_NAMES)) {
+            return this.parseTickerResult(parsed);
+        }
+        if (matchesToolSet(toolName, BALANCE_TOOL_NAMES)) {
+            return this.parseBalanceResult(parsed);
+        }
+        // Unrecognized tool — ignore
+        logger.debug(TAG, `Ignoring tool result: ${toolName}`);
+        return [];
+    }
+    // ---- Tool result parsers ----
+    parseOrderResult(toolName, result) {
+        if (!result || typeof result !== 'object')
+            return [];
+        // cancel_all_orders may return an array of cancelled orders
+        if (Array.isArray(result)) {
+            const events = [];
+            for (const item of result) {
+                if (item && typeof item === 'object' && 'id' in item) {
+                    const parsed = this.parseSingleOrder(item);
+                    if (parsed.length > 0)
+                        events.push(...parsed);
+                }
+            }
+            return events;
+        }
+        // Single order result
+        if ('id' in result) {
+            return this.parseSingleOrder(result);
+        }
+        // Defense in depth: some envelopes carry the order in a `details` field
+        if ('details' in result) {
+            const details = result.details;
+            if (details && typeof details === 'object' && 'id' in details) {
+                return this.parseSingleOrder(details);
+            }
+        }
+        logger.debug(TAG, `Unexpected order result shape from ${toolName}`);
+        return [];
+    }
+    parseSingleOrder(ccxtOrder) {
+        try {
+            const update = mapCcxtOrderToUpdate(ccxtOrder);
+            if (!update)
+                return []; // Invalid order, already logged by mapper
+            logger.debug(TAG, `Order update: ${update.orderId} → ${update.status}`);
+            return [{ event: 'orderUpdate', data: update }];
+        }
+        catch (err) {
+            logger.warn(TAG, `Failed to map CCXT order: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    parseTickerResult(result) {
+        if (!result || typeof result !== 'object')
+            return [];
+        try {
+            const ticker = mapCcxtTicker(result);
+            if (!ticker)
+                return []; // Invalid ticker, already logged by mapper
+            return [{ event: 'ticker', data: ticker }];
+        }
+        catch (err) {
+            logger.warn(TAG, `Failed to map CCXT ticker: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    parseBalanceResult(_result) {
+        // Balance results are handled by the poller (Phase 7f), not the event parser.
+        // Tool invocation results for balance pass through here but we don't emit
+        // a provider event — the poller computes risk from balance + positions together.
+        logger.debug(TAG, 'Balance tool result received (handled by poller)');
+        return [];
+    }
+    // ---- Assistant buffer management ----
+    /**
+     * Called when a tool ends — resume inactivity timers on all active buffers.
+     * If more assistant text follows the tool call, the timer will be cleared
+     * again by handleAssistant. If not, the buffer flushes after BUFFER_INACTIVITY_MS.
+     */
+    resumeBuffersAfterTool() {
+        for (const [runId, entry] of this.assistantBuffers) {
+            if (!entry.toolActive)
+                continue;
+            entry.toolActive = false;
+            // Reset the inactivity timer to start fresh after tool completion
+            if (entry.inactivityTimer) {
+                clearTimeout(entry.inactivityTimer);
+            }
+            entry.inactivityTimer = setTimeout(() => {
+                const current = this.assistantBuffers.get(runId);
+                if (current && !current.toolActive) {
+                    logger.info(TAG, `Post-tool inactivity timeout for run ${runId} — flushing (${current.text.length} chars)`);
+                    const events = this.flushAssistantBuffer(runId);
+                    if (events.length > 0 && this.onAsyncEvents) {
+                        this.onAsyncEvents(events);
+                    }
+                }
+            }, BUFFER_INACTIVITY_MS);
+            logger.debug(TAG, `Tool ended — resumed inactivity timer for run ${runId}`);
+        }
+    }
+    flushAssistantBuffer(runId) {
+        const entry = this.assistantBuffers.get(runId);
+        if (entry?.inactivityTimer) {
+            clearTimeout(entry.inactivityTimer);
+        }
+        this.assistantBuffers.delete(runId);
+        if (!entry || entry.text.trim().length === 0)
+            return [];
+        const msgId = `agent-msg-${runId}`;
+        logger.debug(TAG, `Flushing assistant buffer for run ${runId} (${entry.text.length} chars)`);
+        // Emit chatMessageEnd so the UI finalizes the streaming message.
+        // Also emit legacy chatMessage for backward compatibility (DB persistence, etc.).
+        const message = {
+            id: msgId,
+            role: 'agent',
+            content: entry.text,
+            timestamp: new Date().toISOString(),
+        };
+        return [
+            { event: 'chatMessageEnd', data: { id: msgId, content: entry.text } },
+            { event: 'chatMessage', data: { message } },
+        ];
+    }
+    /** Prune buffers older than BUFFER_EXPIRY_MS to prevent memory leaks from abandoned runs */
+    pruneExpiredBuffers() {
+        const cutoff = Date.now() - BUFFER_EXPIRY_MS;
+        for (const [runId, entry] of this.assistantBuffers) {
+            if (entry.lastUpdate < cutoff) {
+                logger.warn(TAG, `Pruning expired assistant buffer for run ${runId} (${entry.text.length} chars)`);
+                if (entry.inactivityTimer)
+                    clearTimeout(entry.inactivityTimer);
+                this.assistantBuffers.delete(runId);
+            }
+        }
+    }
+    // ---- Error rate tracking ----
+    /** In-place prune of error timestamps outside the rolling window */
+    pruneErrorTimestamps() {
+        const cutoff = Date.now() - ERROR_WINDOW_MS;
+        // Timestamps are appended chronologically, so find first valid index
+        let firstValid = 0;
+        while (firstValid < this.errorTimestamps.length && this.errorTimestamps[firstValid] <= cutoff) {
+            firstValid++;
+        }
+        if (firstValid > 0) {
+            this.errorTimestamps.splice(0, firstValid);
+        }
+    }
+}
+// ---- Helpers ----
+/**
+ * Unwrap the OpenClaw tool envelope if present.
+ * Tool results may be double-wrapped: { result: { content: [{ text: "..." }] } }
+ */
+function unwrapToolEnvelope(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const obj = data;
+    // Check for envelope shape: { result: { content: [{ type: "text", text: "..." }] } }
+    if (obj.result && typeof obj.result === 'object') {
+        const result = obj.result;
+        if (Array.isArray(result.content) && result.content.length > 0) {
+            const first = result.content[0];
+            if (typeof first.text === 'string') {
+                try {
+                    return JSON.parse(first.text);
+                }
+                catch {
+                    return first.text;
+                }
+            }
+        }
+    }
+    // Single-level envelope: { content: [{ type: "text", text: "..." }], details?: ... }
+    // (WS agent event stream — ToolResult from plugin)
+    if (Array.isArray(obj.content) && obj.content.length > 0) {
+        const first = obj.content[0];
+        if (typeof first.text === 'string') {
+            try {
+                return JSON.parse(first.text);
+            }
+            catch {
+                return first.text;
+            }
+        }
+    }
+    return data;
+}