@reefclaw/openclaw-plugin 0.1.0

package/bridge/gateway/gateway-config.d.ts

@@ -0,0 +1,39 @@
+export interface GatewayConfig {
+    /** Full gateway URL, e.g. "http://localhost:18789" */
+    gatewayUrl: string;
+    /** Auth token for gateway API + WebSocket */
+    gatewayToken: string;
+    /** Trading symbol, e.g. "BTC/USDT" */
+    symbol: string;
+    /** Intelligence service URL (optional — regime classification) */
+    intelligenceUrl?: string;
+    /** Connection token for intelligence service auth */
+    connectionToken?: string;
+}
+/** CLI args specific to gateway provider */
+export interface GatewayCliArgs {
+    gatewayUrl?: string;
+    gatewayToken?: string;
+    symbol?: string;
+    intelligenceUrl?: string;
+}
+/**
+ * Resolve gateway connection config with priority:
+ * 1. CLI args (--gateway-url, --gateway-token, --symbol)
+ * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
+ * 3. OpenClaw config file (~/.openclaw/openclaw.json)
+ * 4. Defaults (localhost:18789, BTC/USDT)
+ *
+ * Returns null for gatewayToken if it can't be resolved (caller must handle).
+ */
+export declare function resolveGatewayConfig(args: GatewayCliArgs): {
+    gatewayUrl: string;
+    gatewayToken: string | null;
+    symbol: string;
+    intelligenceUrl: string | null;
+};
+/**
+ * Validate that the resolved config has all required fields.
+ * Returns a fully typed GatewayConfig or null if token is missing.
+ */
+export declare function validateGatewayConfig(resolved: ReturnType<typeof resolveGatewayConfig>): GatewayConfig | null;

package/bridge/gateway/gateway-config.js

@@ -0,0 +1,86 @@
+// Gateway config auto-discovery for OpenClaw integration.
+// Reads gateway connection details from ~/.openclaw/openclaw.json (JSON5).
+// Config priority: CLI args > env vars > openclaw.json > defaults.
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import JSON5 from 'json5';
+import { logger } from '../logger.js';
+const TAG = 'gateway-config';
+const DEFAULT_GATEWAY_PORT = 18789;
+const DEFAULT_GATEWAY_HOST = 'localhost';
+const DEFAULT_SYMBOL = 'BTC/USDT';
+// ---- Read OpenClaw config file ----
+function getConfigPath() {
+    return process.env.OPENCLAW_CONFIG_PATH
+        || join(homedir(), '.openclaw', 'openclaw.json');
+}
+function readOpenClawJson() {
+    const configPath = getConfigPath();
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const config = JSON5.parse(raw);
+        logger.debug(TAG, `Read OpenClaw config from ${configPath}`);
+        return config;
+    }
+    catch {
+        logger.debug(TAG, `Could not read OpenClaw config from ${configPath}`);
+        return null;
+    }
+}
+// ---- Resolve gateway config ----
+/**
+ * Resolve gateway connection config with priority:
+ * 1. CLI args (--gateway-url, --gateway-token, --symbol)
+ * 2. Env vars (OPENCLAW_GATEWAY_URL, OPENCLAW_GATEWAY_TOKEN, REEFCLAW_SYMBOL)
+ * 3. OpenClaw config file (~/.openclaw/openclaw.json)
+ * 4. Defaults (localhost:18789, BTC/USDT)
+ *
+ * Returns null for gatewayToken if it can't be resolved (caller must handle).
+ */
+export function resolveGatewayConfig(args) {
+    const ocConfig = readOpenClawJson();
+    // --- Gateway URL ---
+    // CLI > env > construct from openclaw.json port > default
+    const port = ocConfig?.gateway?.port ?? DEFAULT_GATEWAY_PORT;
+    const defaultUrl = `http://${DEFAULT_GATEWAY_HOST}:${port}`;
+    const gatewayUrl = args.gatewayUrl
+        || process.env.OPENCLAW_GATEWAY_URL
+        || defaultUrl;
+    // --- Gateway token ---
+    // CLI > env > openclaw.json gateway.auth.token
+    const fileToken = ocConfig?.gateway?.auth?.token ?? null;
+    const gatewayToken = args.gatewayToken
+        || process.env.OPENCLAW_GATEWAY_TOKEN
+        || fileToken;
+    if (fileToken && !args.gatewayToken && !process.env.OPENCLAW_GATEWAY_TOKEN) {
+        logger.info(TAG, 'Using gateway token from OpenClaw config');
+    }
+    // --- Symbol ---
+    // CLI > env > default
+    const symbol = args.symbol
+        || process.env.REEFCLAW_SYMBOL
+        || DEFAULT_SYMBOL;
+    if (!gatewayToken) {
+        logger.warn(TAG, 'Gateway token not found in CLI args, env vars, or OpenClaw config');
+    }
+    // --- Intelligence URL ---
+    // CLI > env > default
+    const intelligenceUrl = args.intelligenceUrl
+        || process.env.REEFCLAW_INTELLIGENCE_URL
+        || null;
+    if (intelligenceUrl) {
+        logger.info(TAG, `Intelligence service: ${intelligenceUrl}`);
+    }
+    logger.debug(TAG, `Resolved: url=${gatewayUrl}, token=${gatewayToken ? '***' : '(none)'}, symbol=${symbol}`);
+    return { gatewayUrl, gatewayToken, symbol, intelligenceUrl };
+}
+/**
+ * Validate that the resolved config has all required fields.
+ * Returns a fully typed GatewayConfig or null if token is missing.
+ */
+export function validateGatewayConfig(resolved) {
+    if (!resolved.gatewayToken)
+        return null;
+    return resolved;
+}

package/bridge/gateway/gateway-http-client.d.ts

@@ -0,0 +1,50 @@
+import type { GatewayConfig } from './gateway-config.js';
+export declare class GatewayHttpError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+/** Parsed result of a successful tool invocation */
+export interface InvokeResult<T = unknown> {
+    data: T;
+    raw: string;
+}
+export interface HealthResponse {
+    ok: boolean;
+    [key: string]: unknown;
+}
+export declare class GatewayHttpClient {
+    private readonly baseUrl;
+    private token;
+    constructor(config: Pick<GatewayConfig, 'gatewayUrl' | 'gatewayToken'>);
+    /**
+     * Update the auth token — called after WS handshake obtains a device token.
+     * The gateway issues device tokens during the WS connect handshake.
+     * REST API calls must use this device token, not the raw gateway auth token.
+     */
+    setToken(token: string): void;
+    /**
+     * Invoke a tool on the OpenClaw gateway.
+     *
+     * Handles the nested response envelope:
+     *   { ok, result: { content: [{ type: "text", text: "<JSON-string>" }] } }
+     *
+     * The actual tool result is JSON-stringified inside result.content[0].text,
+     * so we parse twice: once for the outer envelope, once for the inner text.
+     */
+    invoke<T = unknown>(tool: string, args: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+        sessionKey?: string;
+        action?: string;
+    }): Promise<InvokeResult<T>>;
+    /**
+     * Invoke a tool with emergency timeout (5s).
+     * Convenience wrapper for kill/flatten operations that bypass the agent.
+     */
+    invokeEmergency<T = unknown>(tool: string, args: Record<string, unknown>): Promise<InvokeResult<T>>;
+    /**
+     * Check gateway health via GET /health.
+     */
+    health(timeoutMs?: number): Promise<HealthResponse>;
+    private describeHttpError;
+}

package/bridge/gateway/gateway-http-client.js

@@ -0,0 +1,165 @@
+// HTTP client for the OpenClaw gateway REST API.
+// Wraps POST /tools/invoke with double-envelope unwrapping and GET /health.
+import { logger } from '../logger.js';
+const TAG = 'gateway-http';
+// ---- Timeout defaults ----
+const DEFAULT_TIMEOUT_MS = 10_000;
+const EMERGENCY_TIMEOUT_MS = 5_000;
+// ---- Error types ----
+export class GatewayHttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'GatewayHttpError';
+    }
+}
+// ---- Client ----
+export class GatewayHttpClient {
+    baseUrl;
+    token;
+    constructor(config) {
+        // Convert ws:// → http:// and wss:// → https:// for HTTP requests
+        const url = config.gatewayUrl
+            .replace(/^wss:\/\//, 'https://')
+            .replace(/^ws:\/\//, 'http://')
+            .replace(/\/$/, '');
+        this.baseUrl = url;
+        this.token = config.gatewayToken;
+    }
+    /**
+     * Update the auth token — called after WS handshake obtains a device token.
+     * The gateway issues device tokens during the WS connect handshake.
+     * REST API calls must use this device token, not the raw gateway auth token.
+     */
+    setToken(token) {
+        this.token = token;
+        logger.info(TAG, 'HTTP client token updated (device token from WS handshake)');
+    }
+    /**
+     * Invoke a tool on the OpenClaw gateway.
+     *
+     * Handles the nested response envelope:
+     *   { ok, result: { content: [{ type: "text", text: "<JSON-string>" }] } }
+     *
+     * The actual tool result is JSON-stringified inside result.content[0].text,
+     * so we parse twice: once for the outer envelope, once for the inner text.
+     */
+    async invoke(tool, args, opts) {
+        const url = `${this.baseUrl}/tools/invoke`;
+        const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const body = { tool, args };
+        if (opts?.sessionKey)
+            body.sessionKey = opts.sessionKey;
+        if (opts?.action)
+            body.action = opts.action;
+        logger.debug(TAG, `POST ${url} tool=${tool} args_keys=[${Object.keys(args).join(',')}]`);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.token}`,
+                },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new GatewayHttpError(`Request timed out after ${timeoutMs}ms`, 0);
+            }
+            throw new GatewayHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        // Handle HTTP error codes
+        if (!res.ok) {
+            let errorBody;
+            try {
+                errorBody = await res.json();
+            }
+            catch {
+                errorBody = await res.text().catch(() => null);
+            }
+            const msg = this.describeHttpError(res.status, tool, errorBody);
+            throw new GatewayHttpError(msg, res.status, errorBody);
+        }
+        // Parse outer envelope
+        const envelope = (await res.json());
+        if (!envelope.ok) {
+            throw new GatewayHttpError(`Tool invoke failed: ${envelope.error?.message ?? 'unknown error'}`, res.status, envelope);
+        }
+        // Unwrap nested envelope: result.content[0].text contains JSON string
+        const textContent = envelope.result?.content?.[0]?.text;
+        if (textContent === undefined) {
+            throw new GatewayHttpError('Unexpected response format: missing result.content[0].text', res.status, envelope);
+        }
+        // Parse the inner JSON string
+        let data;
+        try {
+            data = JSON.parse(textContent);
+        }
+        catch {
+            throw new GatewayHttpError('Failed to parse inner JSON from result.content[0].text', res.status, { raw: textContent });
+        }
+        logger.debug(TAG, `Tool ${tool} returned successfully`);
+        return { data, raw: textContent };
+    }
+    /**
+     * Invoke a tool with emergency timeout (5s).
+     * Convenience wrapper for kill/flatten operations that bypass the agent.
+     */
+    async invokeEmergency(tool, args) {
+        return this.invoke(tool, args, { timeoutMs: EMERGENCY_TIMEOUT_MS });
+    }
+    /**
+     * Check gateway health via GET /health.
+     */
+    async health(timeoutMs = DEFAULT_TIMEOUT_MS) {
+        const url = `${this.baseUrl}/health`;
+        logger.debug(TAG, `GET ${url}`);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, {
+                method: 'GET',
+                headers: { 'Authorization': `Bearer ${this.token}` },
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new GatewayHttpError(`Health check timed out after ${timeoutMs}ms`, 0);
+            }
+            throw new GatewayHttpError(`Network error: ${err instanceof Error ? err.message : String(err)}`, 0);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            throw new GatewayHttpError(`Health check failed: HTTP ${res.status}`, res.status);
+        }
+        return (await res.json());
+    }
+    // ---- Private ----
+    describeHttpError(status, tool, body) {
+        const bodyMsg = body && typeof body === 'object' && 'error' in body
+            ? `: ${body.error?.message ?? ''}`
+            : '';
+        switch (status) {
+            case 400: return `Bad request for tool "${tool}"${bodyMsg}`;
+            case 401: return `Unauthorized — invalid or expired gateway token${bodyMsg}`;
+            case 404: return `Tool "${tool}" not found (not in allowlist or doesn't exist)${bodyMsg}`;
+            case 405: return `Method not allowed for tool "${tool}"${bodyMsg}`;
+            default: return `HTTP ${status} invoking tool "${tool}"${bodyMsg}`;
+        }
+    }
+}

package/bridge/gateway/gateway-ws-client.d.ts

@@ -0,0 +1,116 @@
+import { type ReconnectConfig as BaseReconnectConfig } from '../utils/reconnect.js';
+import type { GatewayConfig } from './gateway-config.js';
+interface ReconnectConfig extends BaseReconnectConfig {
+    maxAttempts: number;
+}
+/** hello-ok response payload from gateway */
+export interface HelloOkPayload {
+    type: 'hello-ok';
+    protocol: number;
+    policy: {
+        tickIntervalMs: number;
+        maxPayload: number;
+    };
+    snapshot: {
+        presence: Record<string, unknown>;
+        health: Record<string, unknown>;
+        stateVersion: number;
+        uptimeMs: number;
+    };
+    auth: {
+        deviceToken: string;
+        role: string;
+        scopes: string[];
+    };
+}
+export type GatewayWsEvent = 'connected' | 'disconnected' | 'reconnecting' | 'failed' | 'agent' | 'presence' | 'tick' | 'shutdown';
+export type GatewayWsEventPayload = {
+    connected: HelloOkPayload;
+    disconnected: {
+        code: number;
+        reason: string;
+    };
+    reconnecting: {
+        attempt: number;
+        delayMs: number;
+    };
+    failed: {
+        reason: string;
+    };
+    agent: {
+        runId: string;
+        stream: string;
+        data: unknown;
+        seq?: number;
+    };
+    presence: {
+        payload: unknown;
+        seq?: number;
+    };
+    tick: void;
+    shutdown: void;
+};
+type EventListener<E extends GatewayWsEvent> = (payload: GatewayWsEventPayload[E]) => void;
+export type GatewayWsState = 'disconnected' | 'connecting' | 'handshaking' | 'connected' | 'reconnecting' | 'failed';
+export declare class GatewayWsClient {
+    private ws;
+    private state;
+    private attempt;
+    private reconnectTimer;
+    private staleWarnTimer;
+    private staleReconnectTimer;
+    private tickIntervalMs;
+    private pendingRpcs;
+    private readonly reconnectConfig;
+    private destroyed;
+    /** Stored device token from hello-ok for future connects */
+    private deviceToken;
+    /** Last hello-ok payload — contains initial snapshot */
+    private lastHelloOk;
+    /** Event listeners */
+    private listeners;
+    private readonly gatewayUrl;
+    private readonly gatewayToken;
+    constructor(config: Pick<GatewayConfig, 'gatewayUrl' | 'gatewayToken'>, reconnect?: Partial<ReconnectConfig>);
+    /** Start the WebSocket connection and handshake */
+    connect(): void;
+    /** Disconnect and clean up. Cannot reconnect after this. */
+    destroy(): void;
+    /**
+     * Send an RPC request and wait for the response.
+     * Used for: agent (chat), health, status
+     */
+    sendRpc(method: string, params?: Record<string, unknown>): Promise<unknown>;
+    /** Register an event listener */
+    on<E extends GatewayWsEvent>(event: E, listener: EventListener<E>): void;
+    /** Remove an event listener */
+    off<E extends GatewayWsEvent>(event: E, listener: EventListener<E>): void;
+    /** Get current connection state */
+    getState(): GatewayWsState;
+    /** Get the hello-ok snapshot from the last successful connection */
+    getHelloOk(): HelloOkPayload | null;
+    /** Get stored device token (for future connects) */
+    getDeviceToken(): string | null;
+    private handleMessage;
+    private handleResponse;
+    private handleEvent;
+    /**
+     * Step 1: Receive connect.challenge with {nonce, ts}.
+     * Step 2: Send connect request with auth token.
+     */
+    private handleChallenge;
+    /**
+     * Step 3: Process hello-ok response.
+     * Extracts policy, snapshot, and device token.
+     */
+    private handleHelloOk;
+    /** Reset the stale timers — called on any incoming event/tick */
+    private resetStaleTimer;
+    private clearStaleTimer;
+    private scheduleReconnect;
+    private clearReconnectTimer;
+    private setState;
+    private emit;
+    private rejectAllPending;
+}
+export {};