@reefclaw/openclaw-plugin 0.1.0

package/bridge/providers/emergency-commands.js

@@ -0,0 +1,235 @@
+// Stateless emergency command handlers extracted from GatewayProvider.
+// Functions return results — callers apply state changes (agentMode, emitAgentState).
+import { logger } from '../logger.js';
+const TAG = 'emergency';
+/** Distinct human-readable reasons from the rejected entries of an
+ *  allSettled batch — surfaced in EmergencyResult.details so the dashboard
+ *  shows WHY a close/cancel failed, not just that it did. Capped so a
+ *  many-position failure doesn't produce an unreadable wall. */
+function rejectionReasons(results, max = 3) {
+    const reasons = results
+        .filter((r) => r.status === 'rejected')
+        .map((r) => (r.reason instanceof Error ? r.reason.message : String(r.reason)));
+    const distinct = [...new Set(reasons)];
+    const shown = distinct.slice(0, max).join('; ');
+    return distinct.length > max ? `${shown}; …` : shown;
+}
+// ---- Async commands (need HTTP + tools) ----
+/**
+ * Kill: stop the agent and cancel WORKING orders, while PRESERVING protective
+ * brackets. A protective order (exchange-side STOP_MARKET / TAKE_PROFIT_MARKET)
+ * is the only thing guarding an open position once the agent is halted (nothing
+ * will re-attach a stop). Kill cancels only the agent's working orders (pending
+ * entries / adds), PORTFOLIO-WIDE, and keeps every protective leg in place. To
+ * actually exit a position, use Flatten.
+ *
+ * Bracket preservation is defence-in-depth: the plugin's `cancelAllOrders`
+ * already skips ReefClaw-cid brackets, so the old per-symbol kill never stripped
+ * a ReefClaw bracket — this skill-side `protective` filter is BROADER (it also
+ * preserves externally-placed / non-ReefClaw-cid stops) and portfolio-wide.
+ *
+ * Caller must set agentMode = 'STOPPED' after this returns, and should pass a
+ * FRESH all-symbols order snapshot (see the gateway wrapper).
+ */
+export async function executeKill(ctx, openOrders) {
+    if (!ctx.http) {
+        return { action: 'kill', executed: false, timestamp: new Date().toISOString(), details: 'HTTP client not initialized' };
+    }
+    // Protective = a stop/TP bracket (reduceOnly OR closePosition OR stop-type;
+    // see mapCcxtOrder/isProtectiveOrder). Working = everything else (entries /
+    // adds). Preserve protective so an open position is never left naked.
+    const working = openOrders.filter((o) => o.protective !== true);
+    const preserved = openOrders.length - working.length;
+    const preservedNote = preserved > 0 ? `; preserved ${preserved} protective bracket order(s)` : '';
+    // executed:true ONLY when the agent halt (the caller sets STOPPED
+    // unconditionally after this returns) is accompanied by a clean order
+    // sweep. Failed/impossible cancels leave live working orders behind an
+    // operator who just hit Kill — that must render as Failed + details on the
+    // dashboard, never a clean green.
+    let executed = true;
+    let details;
+    const cancelTool = ctx.toolMap.cancel_order;
+    if (cancelTool && working.length > 0) {
+        // Primary: cancel each working order individually (portfolio-wide), so the
+        // protective brackets are never touched.
+        const results = await Promise.allSettled(working.map((order) => ctx.http.invokeEmergency(cancelTool, { id: order.id, symbol: order.symbol })));
+        const succeeded = results.filter((r) => r.status === 'fulfilled').length;
+        const failed = results.filter((r) => r.status === 'rejected').length;
+        if (failed > 0) {
+            executed = false;
+            details = `Agent halted, but cancelled only ${succeeded}/${working.length} working order(s) (${failed} failed: ${rejectionReasons(results)})${preservedNote}`;
+            logger.error(TAG, details);
+        }
+        else {
+            details = `Cancelled ${succeeded}/${working.length} working order(s)${preservedNote}`;
+        }
+    }
+    else if (working.length === 0) {
+        details = preserved > 0
+            ? `No working orders to cancel${preservedNote}`
+            : 'No open orders to cancel';
+    }
+    else {
+        // Degenerate fallback: cancel_order wasn't discovered. cancel_all_orders is
+        // per-symbol; the plugin's implementation preserves ReefClaw-cid brackets,
+        // but (unlike the skill `protective` filter above) it can't spare an
+        // externally-placed / non-ReefClaw-cid stop — so warn.
+        const cancelAllTool = ctx.toolMap.cancel_all_orders;
+        if (cancelAllTool) {
+            const symbols = [...new Set(working.map((o) => o.symbol))];
+            const results = await Promise.allSettled(symbols.map((s) => ctx.http.invokeEmergency(cancelAllTool, { symbol: s })));
+            const failed = results.filter((r) => r.status === 'rejected').length;
+            if (failed > 0) {
+                executed = false;
+                details = `Agent halted, but cancel_all_orders failed on ${failed}/${symbols.length} symbol(s) (${rejectionReasons(results)}) — some orders may remain live`;
+                logger.error(TAG, details);
+            }
+            else {
+                details = `cancel_order unavailable — used cancel_all_orders on ${symbols.length} symbol(s) (plugin preserves ReefClaw-cid brackets; a non-cid/external stop is not spared)`;
+                logger.warn(TAG, details);
+            }
+        }
+        else {
+            executed = false;
+            details = 'No cancel tool available (neither cancel_order nor cancel_all_orders discovered) — agent halted, orders left in place';
+            logger.warn(TAG, details);
+        }
+    }
+    return { action: 'kill', executed, timestamp: new Date().toISOString(), details };
+}
+/**
+ * Flatten: close all open positions at market.
+ * Caller must set agentMode = 'STOPPED' after this returns.
+ */
+export async function executeFlatten(ctx, cachedPositions) {
+    if (!ctx.http) {
+        return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details: 'HTTP client not initialized' };
+    }
+    // Try to fetch fresh positions; fall back to cached on failure.
+    // Flatten is PORTFOLIO-WIDE — fetch ALL symbols (no symbol filter). Passing
+    // ctx.symbol here narrowed the result to a single symbol, so positions on
+    // every other symbol were silently skipped and never closed. The cached
+    // fallback (this.positions) is already all-symbols.
+    let positions = cachedPositions;
+    const fetchTool = ctx.toolMap.fetch_positions;
+    if (fetchTool) {
+        try {
+            const result = await ctx.http.invokeEmergency(fetchTool, {});
+            if (Array.isArray(result.data)) {
+                positions = result.data;
+            }
+            else {
+                // Mirror gateway.ts fetchFreshPositions: a non-array response must
+                // fall back to cached — letting it through would make the .filter
+                // below throw and abort the entire flatten.
+                logger.warn(TAG, `fetch_positions returned non-array (${typeof result.data}) — using cached positions`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `Fresh position fetch failed, using cached: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Filter to non-zero positions
+    const openPositions = positions.filter((p) => (p.contracts ?? 0) !== 0);
+    if (openPositions.length === 0) {
+        return { action: 'flatten', executed: true, timestamp: new Date().toISOString(), details: 'No positions to close' };
+    }
+    // Close each position
+    const closeTool = ctx.toolMap.close_position;
+    const createTool = ctx.toolMap.create_order;
+    const results = await Promise.allSettled(openPositions.map((pos) => {
+        if (closeTool) {
+            // reason='operator_command' is MANDATORY: close_position's schema gate
+            // (validateClosePosition) rejects any close lacking a reason, and only
+            // operator_command bypasses the assessment requirement. Without it the
+            // operator Flatten is silently rejected at the API boundary and the
+            // position never closes. See plugin/src/tools/close-position.ts.
+            return ctx.http.invokeEmergency(closeTool, { symbol: pos.symbol, reason: 'operator_command' });
+        }
+        else if (createTool) {
+            // Fallback: opposing market order. reduceOnly is MANDATORY — this
+            // order may only shrink the position. Without it, a race (position
+            // already closed by a bracket fill / a smaller live quantity than the
+            // snapshot) turns the "close" into a NEW opposing position — a flip.
+            const side = pos.side === 'long' ? 'sell' : 'buy';
+            return ctx.http.invokeEmergency(createTool, {
+                symbol: pos.symbol,
+                type: 'market',
+                side,
+                amount: Math.abs(pos.contracts ?? 0),
+                reduceOnly: true,
+            });
+        }
+        else {
+            return Promise.reject(new Error('No close_position or create_order tool available'));
+        }
+    }));
+    const succeeded = results.filter((r) => r.status === 'fulfilled').length;
+    const failed = results.filter((r) => r.status === 'rejected').length;
+    // Any un-closed position = NOT executed. "Closed 1/5" rendering as a green
+    // "Flattened" would leave the operator believing they're flat while 4 real
+    // positions stay live — the dashboard must show Failed + which/why.
+    if (succeeded === 0 && openPositions.length > 0) {
+        const details = `Failed to close any of ${openPositions.length} position(s): ${rejectionReasons(results)}`;
+        logger.error(TAG, details);
+        return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details };
+    }
+    if (failed > 0) {
+        const details = `Closed ${succeeded}/${openPositions.length} positions (${failed} failed: ${rejectionReasons(results)})`;
+        logger.error(TAG, details);
+        return { action: 'flatten', executed: false, timestamp: new Date().toISOString(), details };
+    }
+    const details = `Closed ${succeeded}/${openPositions.length} positions`;
+    return { action: 'flatten', executed: true, timestamp: new Date().toISOString(), details };
+}
+// ---- Sync commands (pure state transitions) ----
+/**
+ * Pause: prevent new entries, keep existing positions.
+ * Returns the new agent mode if the transition is valid.
+ */
+export function executePause(currentMode) {
+    if (currentMode === 'PAUSED') {
+        return {
+            result: { action: 'pause', executed: true, timestamp: new Date().toISOString(), details: 'Already paused' },
+            newMode: 'PAUSED',
+        };
+    }
+    if (currentMode === 'STOPPED') {
+        return {
+            result: { action: 'pause', executed: false, timestamp: new Date().toISOString(), details: 'Cannot pause — agent is stopped' },
+            newMode: 'STOPPED',
+        };
+    }
+    return {
+        result: { action: 'pause', executed: true, timestamp: new Date().toISOString(), details: 'Trading paused' },
+        newMode: 'PAUSED',
+    };
+}
+/**
+ * Resume: re-enable entries.
+ * Returns the new agent mode if the transition is valid.
+ */
+export function executeResume(currentMode) {
+    if (currentMode === 'ACTIVE') {
+        return {
+            result: { action: 'resume', executed: true, timestamp: new Date().toISOString(), details: 'Already active' },
+            newMode: 'ACTIVE',
+        };
+    }
+    if (currentMode === 'STOPPED') {
+        return {
+            result: { action: 'resume', executed: true, timestamp: new Date().toISOString(), details: 'Trading resumed from stopped state' },
+            newMode: 'ACTIVE',
+        };
+    }
+    if (currentMode === 'ERROR') {
+        return {
+            result: { action: 'resume', executed: false, timestamp: new Date().toISOString(), details: 'Cannot resume — agent is in error state' },
+            newMode: 'ERROR',
+        };
+    }
+    return {
+        result: { action: 'resume', executed: true, timestamp: new Date().toISOString(), details: 'Trading resumed' },
+        newMode: 'ACTIVE',
+    };
+}

package/bridge/providers/gateway.d.ts

@@ -0,0 +1,322 @@
+import type { OpenClawProvider, ProviderEvents, ProviderEventName } from '../provider.js';
+import type { EmergencyAction, ReconciliationSnapshot, TradingMode } from '../types.js';
+import type { GatewayConfig } from '../gateway/gateway-config.js';
+import { type GetBracketConfigOutcome, type SetBracketRequirementOutcome, type BracketRequirementFlag, type SetTradingModeOutcome, type SetExchangeCredentialsOutcome, type TestExchangeCredentialsOutcome, type ClearExchangeCredentialsOutcome } from './onboarding-commands.js';
+/** Decide whether the session-start-NAV anchor needs to be (re)set. Pure so it
+ *  can be unit-tested without the full provider. Returns true when the anchor
+ *  has never been set, OR — for PAPER only — when it belongs to a previous UTC
+ *  day (so Day P&L re-anchors at midnight). Live/shadow anchor once and then
+ *  sync to the plugin's Binance income-endpoint value, so they never
+ *  self-re-anchor here. */
+export declare function shouldAnchorSessionNav(args: {
+    sessionStartNav: number;
+    sessionDate: string | null;
+    today: string;
+    mode: TradingMode;
+}): boolean;
+export declare class GatewayProvider implements OpenClawProvider {
+    private readonly config;
+    private http;
+    private wsClient;
+    private poller;
+    private eventParser;
+    private toolMap;
+    private agentMode;
+    private lastKnownStrategy;
+    /** Agent display name + live model id, resolved from the gateway (best-effort).
+     *  Surfaced in agent_state so the dashboard header can show the real agent +
+     *  model instead of a hardcoded placeholder. Empty until the gateway answers. */
+    private agentIdentity;
+    /** Emit the one-time rollout probe (gateway response shape) only on the first attempt. */
+    private loggedAgentIdentityProbe;
+    /** Live heartbeat cadence (seconds), read from the OpenClaw cron store; cached 60s. */
+    private heartbeatSeconds?;
+    private heartbeatReadAtMs;
+    private loggedHeartbeat;
+    private lastTicker;
+    private positions;
+    private balance;
+    /** Today's realized PnL (filtered by closedAt) from plugin trade history. */
+    private realizedPnlToday;
+    /** Cumulative all-time realized PnL — used for the webapp KPI strip. */
+    private realizedPnlAllTime;
+    /** Paper session execution costs (since plugin boot), forwarded to the
+     *  dashboard cost cells so "Fees"/"Avg Slip" reflect the drag already in NAV
+     *  instead of reading $0 (M1). Null in live (LiveAdapter omits them). */
+    private paperSessionFees;
+    private paperAvgSlippageBps;
+    /** Mark-to-market equity from plugin (wallet + collateral + unrealized). */
+    private equity;
+    private openOrders;
+    private startTime;
+    /** Session start NAV — -1 means "not yet set", 0 is valid (fresh account). */
+    private sessionStartNav;
+    /** UTC date (YYYY-MM-DD) the current sessionStartNav anchor belongs to.
+     *  Null until first anchored. Used to re-anchor Day P&L at UTC midnight —
+     *  without it a long-running PAPER session kept yesterday's anchor and Day
+     *  P&L / Realized accumulated across days. */
+    private sessionDate;
+    /** Track whether we've received at least one positions poll (needed for equity calculation). */
+    private hasReceivedPositions;
+    /** Track whether we've received at least one balance poll (needed for equity calculation). */
+    private hasReceivedBalance;
+    private readonly quoteCurrency;
+    private orderTimestamps;
+    private cancelTimestamps;
+    private agentStateInterval;
+    private toolRetryInterval;
+    private regimeInterval;
+    private signalInterval;
+    private missionInterval;
+    private analyticsInterval;
+    private decisionTraceInterval;
+    private pendingStartTimers;
+    private started;
+    private startedAt;
+    private lastSeenMissionIds;
+    private intelErrors;
+    private lastCryptoMetrics;
+    private lastVolumeAnalysis;
+    private atrData;
+    private atrSampleCount;
+    private currentRegime;
+    /** Timestamp of the most recent trade (fill event) — used in buildAgentState */
+    private lastTradeTs;
+    /** Tracks open position entries for computing trade results on close.
+     *  Key: `symbol:side` (e.g. "BTC/USDT:long"), Value: { entryPrice, quantity, side, entryTime, missionId?, setupType?, regime?, confluenceScore? } */
+    private openTradeEntries;
+    /** Potential closes awaiting 2-poll confirmation. Binance's fetchPositions
+     *  occasionally returns a held position as missing or zero-contract for a
+     *  single poll; those transient drops were the root cause of ~350 phantom
+     *  trade_results rows/day. We only treat a position as closed after it's
+     *  been absent on TWO consecutive polls. Key: `symbol:side`. */
+    private pendingCloses;
+    /** Tracks whether the previous poll returned an empty / all-flat positions
+     *  snapshot while we were holding non-zero positions. A single empty poll is
+     *  treated as tentative (most often a Binance 429 / partial response). We
+     *  skip the diff detector and do NOT overwrite this.positions until the
+     *  next poll confirms — without this guard, the next non-empty poll re-emits
+     *  synthetic OPEN fills for positions that were there all along (the
+     *  open-side mirror of the close-side phantom that pendingCloses guards
+     *  against). See Track 1 verification 2026-04-21 +
+     *  docs/TRADE_AUDIT_TRAIL_PLAN.md Phase 0. */
+    private pendingEmptyPoll;
+    /** In-flight trade result reports — drained on stop() to prevent data loss during kill/flatten. */
+    private inFlightReports;
+    /** File-backed retry queue for failed trade reports */
+    private readonly retryQueuePath;
+    private retryTimer;
+    private tradingMode;
+    private readonly listeners;
+    constructor(config: GatewayConfig);
+    start(): void;
+    stop(): void;
+    /**
+     * Drain in-flight trade result reports. Call during shutdown to prevent
+     * data loss during kill/flatten sequences. Returns when all pending
+     * reports have completed (or timed out).
+     */
+    drainReports(): Promise<void>;
+    private loadRetryQueue;
+    private saveRetryQueue;
+    /** Guards processRetryQueue against overlapping runs — the retry timer fires
+     *  every 60s and startRetryTimer also kicks an immediate run, so a slow
+     *  (100-item × 10s-timeout) drain could still be in flight when the next
+     *  timer ticks. Two concurrent drains would double-POST every queued report
+     *  AND race their reconcile-saves against each other. */
+    private retryInProgress;
+    /** Monotonic tag stamped on every queued report so processRetryQueue can
+     *  remove EXACTLY the reports it delivered when it reconciles the file — a
+     *  blind `save(remaining)` would clobber any report enqueued DURING the
+     *  network phase (read-modify-write race with enqueueFailedReport). */
+    private nextRetryQid;
+    private enqueueFailedReport;
+    private processRetryQueue;
+    private startRetryTimer;
+    private stopRetryTimer;
+    /** Dual-fire dedup. Every critical command fires on BOTH WebSocket and
+     *  HTTP simultaneously (CLAUDE.md: "Agent handles idempotency; first to
+     *  arrive wins") — so each emergency action normally arrives here TWICE,
+     *  ~0-200ms apart. Without dedup a second `flatten` re-fetches positions
+     *  before the first close settles on-exchange and submits a second market
+     *  close — a position-flip risk. Duplicates of the same action while one
+     *  is in flight (or within a short post-completion window) share the
+     *  first invocation's promise/result instead of executing again. */
+    private static readonly EMERGENCY_DEDUP_MS;
+    private emergencyInFlight;
+    executeEmergency(action: EmergencyAction): Promise<{
+        action: string;
+        executed: boolean;
+        timestamp: string;
+        details?: string;
+    }>;
+    private runEmergency;
+    private executeKill;
+    private executeFlatten;
+    private executePause;
+    private executeResume;
+    handleChat(content: string): Promise<{
+        received: boolean;
+        error?: string;
+    }>;
+    closePosition(symbol: string): Promise<{
+        closed: boolean;
+        symbol: string;
+        error?: string;
+    }>;
+    setTradingMode(mode: TradingMode, acknowledged?: boolean): Promise<SetTradingModeOutcome>;
+    setExchangeCredentials(apiKey: string, secret: string, testnet?: boolean): Promise<SetExchangeCredentialsOutcome>;
+    testExchangeCredentials(apiKey: string, secret: string, testnet?: boolean): Promise<TestExchangeCredentialsOutcome>;
+    clearExchangeCredentials(): Promise<ClearExchangeCredentialsOutcome>;
+    /** Operator-only. Read the current bracket-orders config from the plugin. */
+    getBracketConfig(): Promise<GetBracketConfigOutcome>;
+    /** Operator-only. Flip requireStopLoss or requireTakeProfit. */
+    setBracketRequirement(flag: BracketRequirementFlag, value: boolean): Promise<SetBracketRequirementOutcome>;
+    getSnapshot(): Promise<ReconciliationSnapshot>;
+    on<E extends ProviderEventName>(event: E, listener: ProviderEvents[E]): void;
+    off<E extends ProviderEventName>(event: E, listener: ProviderEvents[E]): void;
+    private initialize;
+    /**
+     * Wait for the WS handshake to complete and return the device token.
+     * Returns null if handshake fails or times out.
+     */
+    private waitForDeviceToken;
+    /**
+     * Essential optional tools — retry loop keeps running until these are discovered.
+     * These are needed for position tracking, emergency controls, and trade display.
+     */
+    private static readonly ESSENTIAL_OPTIONAL_TOOLS;
+    /** Check if all essential tools are discovered. */
+    private hasAllEssentialTools;
+    /** Retry tool discovery every 30s until all essential tools are found. */
+    private startToolRetry;
+    private createPoller;
+    private wireWsEvents;
+    private onWsConnected;
+    private onAgentEvent;
+    private onPollerTicker;
+    /** Strip the live-Binance settle suffix (`SOL/USDT:USDT` → `SOL/USDT`)
+     *  to ONE canonical form, matching the webapp/plugin normalizeSymbol
+     *  convention (chart/DB are unsuffixed). The plugin's getPositions
+     *  returns the suffixed CCXT form via REST but the unsuffixed form via
+     *  the WS store; under weight pressure isStoreTrusted() flickers between
+     *  the two, so the raw symbol alternates poll-to-poll. */
+    private canonicalSymbol;
+    private onPollerPositions;
+    /**
+     * Compare previous and current positions from polling.
+     * When a position appears, changes size, or disappears,
+     * emit synthetic orderUpdate events so chart markers show trades.
+     */
+    /** Apply a fresh mark price to a position (mutates in place). */
+    private applyMarkPrice;
+    private detectPositionChanges;
+    /**
+     * Emit a synthetic orderUpdate event derived from position polling data.
+     * Used when WS agent events are unavailable (gateway event filtering).
+     */
+    private emitSyntheticFill;
+    private onPollerBalance;
+    /**
+     * Set session start NAV once both balance AND positions have been received.
+     * Checks persisted file first — if today's NAV was already captured in a
+     * previous skill run, reuse it so Day P&L is stable across restarts.
+     */
+    private trySetSessionStartNav;
+    private onPollerOpenOrders;
+    private onPollerMarketStructure;
+    private onPollerCryptoMetrics;
+    private onPollerVolumeAnalysis;
+    /**
+     * Build and emit a trade journal entry whenever a synthetic fill is detected.
+     * Called from emitSyntheticFill — captures market + risk context at trade time.
+     */
+    private emitTradeJournal;
+    /** Simple heat score (0–100) matching webapp's HeatGauge logic */
+    private computeHeatScoreSimple;
+    /** Cache last market structure for journal entries */
+    private lastMarketStructure;
+    private fetchFreshPositions;
+    private fetchFreshBalance;
+    private fetchFreshOpenOrders;
+    private fetchAgentHealth;
+    /**
+     * Resolve the agent's display name + live model id directly from the gateway.
+     * The primary carrier is the `sessions.list` RPC (rows carry agentId + the
+     * live model); `health` (above) is a secondary feed. Best-effort and
+     * fail-open — the gateway/version may not expose either, in which case the
+     * header simply falls back to its placeholder. Re-emits agent_state on a hit
+     * so the dashboard updates without waiting for the next periodic tick.
+     */
+    private refreshAgentIdentity;
+    /** Merge newly-resolved identity fields into the cache. Returns true if anything changed. */
+    private mergeAgentIdentity;
+    /**
+     * Extract the live model id from a `sessions.list` (or `health`) gateway
+     * payload. We deliberately do NOT take the agent NAME from here: sessions
+     * rows are per-chat and their `name` is a channel/chat id (e.g. a Telegram
+     * id), not the agent's identity — the display name comes from
+     * resolveAgentNameFromIdentity(). The exact shape isn't contractually stable,
+     * so probe the documented paths (row → runtime → defaults → root) and accept
+     * either a bare string or a `{ primary }` object.
+     */
+    private extractAgentModel;
+    /**
+     * Resolve the agent's display name from the OpenClaw workspace IDENTITY.md
+     * (`- **Name:** <X>`), local to this deployment (per-tenant correct — each
+     * trader's own agent has its own IDENTITY.md). Best-effort + fail-open:
+     * returns undefined when the file is missing/unreadable, the field is the
+     * unfilled placeholder, or the value looks like an id rather than a name.
+     */
+    private resolveAgentNameFromIdentity;
+    /**
+     * Live heartbeat cadence in seconds — the agent's TRUE beat interval, read
+     * from the OpenClaw cron store (`~/.openclaw/cron/jobs.json` → the enabled
+     * heartbeat job's `schedule.everyMs`). This is the source of truth: the old
+     * hardcoded 1800 and `agents.defaults.heartbeat` are both stale/wrong once
+     * the operator edits the cron (`openclaw cron ... --every 15m`). Drives both
+     * the "beat every Nm" label and the unresponsive (2×) threshold. Cached 60s;
+     * returns undefined (caller defaults to 1800) when unreadable.
+     */
+    private resolveHeartbeatSeconds;
+    /** Build agent state from internal fields (used by both emitAgentState and getSnapshot). */
+    private buildAgentState;
+    private emitAgentState;
+    private emitRiskUpdate;
+    /** Compute risk metrics — delegates to pure functions in risk-calculator.ts */
+    private computeRiskMetrics;
+    /** Compute total equity — delegates to pure function in risk-calculator.ts */
+    private computeEquity;
+    /** Compute signed notional — delegates to pure function in risk-calculator.ts */
+    private computePositionNotional;
+    /**
+     * Report a completed trade to the Intelligence API for persistent cross-session analytics.
+     * Called when a position closes (detected via position polling diffs).
+     * Handles partial closes: updates remaining quantity in openTradeEntries instead of deleting.
+     *
+     * @param key       Composite key `symbol:side` into openTradeEntries
+     * @param symbol    CCXT symbol (e.g. "BTC/USDT")
+     * @param exitPrice Fill price for the close
+     * @param closedQty Quantity actually closed (may be less than full position for partial closes)
+     */
+    private reportTradeResult;
+    /**
+     * Seed lastTradeTs from Intelligence API on startup. One-shot, best-effort.
+     * Prevents "Last Trade: Never" after every restart when the agent is flat.
+     */
+    private seedLastTradeTs;
+    /** Symbol formatted for intelligence API (BTC/USDT → BTCUSDT). */
+    private get intelligenceSymbol();
+    /** Shared intelligence poller with circuit-breaker (exponential backoff on errors). */
+    private startIntelligencePoller;
+    /** Log first error per poller, suppress subsequent repeats. */
+    private trackIntelError;
+    private startRegimePoller;
+    private startSignalPoller;
+    private startMissionPoller;
+    private startAnalyticsPoller;
+    private startDecisionTracePoller;
+    private static readonly STRATEGY_LABELS;
+    private presentMissionToAgent;
+    private fire;
+}