@reefclaw/connect 0.1.1 → 0.1.3

package/assets/plugin/config/plugin-config-io.d.ts

@@ -2,6 +2,12 @@ import type { TradingMode, ExchangeConfig } from '../types.js';
 /** Full on-disk schema. Unknown keys are preserved on round-trip. */
 export interface PluginConfigFile {
     connectionToken?: string;
+    /** 'on' → the plugin spawns + restarts the relay connector as a child of
+     *  the gateway process (no systemd — OpenClaw is the process manager).
+     *  Written by the npx installer on fresh installs. MUST stay defaulted off:
+     *  prod runs the bridge under systemd and a supervisor there would
+     *  double-connect the relay room. Kill-switch: RC_CONNECTOR_SUPERVISOR=off. */
+    connectorSupervisor?: 'on' | 'off';
     apiBaseUrl?: string;
     intelligenceUrl?: string;
     exchange?: ExchangeConfig;

package/assets/plugin/connector-supervisor.d.ts

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+export interface ConnectorSupervisorOptions {
+    /** Directory holding the placed bridge (default ~/.reefclaw/bridge). */
+    bridgeDir?: string;
+    /** Injectable spawn for tests. */
+    spawnFn?: typeof spawn;
+}
+export interface ConnectorSupervisorHandle {
+    stop(): void;
+    /** Test/debug introspection. */
+    isRunning(): boolean;
+}
+/**
+ * Start supervising the connector. Idempotent per process — repeat calls
+ * (OpenClaw can invoke register() more than once) return the existing handle.
+ * Returns null when the bridge isn't placed on disk (installer not run).
+ */
+export declare function startConnectorSupervisor(opts?: ConnectorSupervisorOptions): ConnectorSupervisorHandle | null;
+/** Test-only: reset the module singleton. */
+export declare function resetConnectorSupervisorForTest(): void;

package/assets/plugin/connector-supervisor.js

@@ -0,0 +1,118 @@
+// Plugin-supervised ReefClaw connector (frictionless-onboarding phase 1).
+//
+// The plugin runs persistently inside the OpenClaw gateway process, so it can
+// supervise the relay connector (the bridge) as a child process — making
+// OpenClaw itself the process manager. This removes every host-level concern
+// from onboarding: no systemd, no terminal, works inside containers, and the
+// connector's lifetime is correctly tied to the gateway's (gateway down ⇒
+// nothing to bridge anyway — the plugin holding the exchange keys lives in
+// the same process).
+//
+// SAFETY: default OFF. Prod runs the bridge as `reefclaw-skill.service`
+// (systemd) — a supervisor turned on there would double-connect the relay
+// room. Only the fresh-install path (the npx installer) writes
+// `connectorSupervisor: 'on'` into ~/.reefclaw/plugin-config.json.
+// Kill-switch: RC_CONNECTOR_SUPERVISOR=off beats config.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { logger } from './logger.js';
+const TAG = 'connector-supervisor';
+const MIN_BACKOFF_MS = 5_000;
+const MAX_BACKOFF_MS = 60_000;
+/** A child that survives this long resets the backoff (it was healthy). */
+const STABLE_RESET_MS = 5 * 60_000;
+let singleton = null;
+/**
+ * Start supervising the connector. Idempotent per process — repeat calls
+ * (OpenClaw can invoke register() more than once) return the existing handle.
+ * Returns null when the bridge isn't placed on disk (installer not run).
+ */
+export function startConnectorSupervisor(opts = {}) {
+    if (singleton)
+        return singleton;
+    const bridgeDir = opts.bridgeDir ?? join(homedir(), '.reefclaw', 'bridge');
+    const indexJs = join(bridgeDir, 'index.js');
+    if (!existsSync(indexJs)) {
+        logger.warn(TAG, `connector not found at ${indexJs} — supervisor idle (run the installer first)`);
+        return null;
+    }
+    const spawnFn = opts.spawnFn ?? spawn;
+    let child = null;
+    let stopped = false;
+    let backoffMs = MIN_BACKOFF_MS;
+    let restartTimer = null;
+    const launch = () => {
+        if (stopped)
+            return;
+        const startedAt = Date.now();
+        // NOT detached: the connector must die with the gateway (a gateway
+        // restart resurrects both, and an orphan bridge can never linger).
+        child = spawnFn(process.execPath, [indexJs, '--provider', 'gateway', '--log-level', 'info'], {
+            cwd: bridgeDir,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        logger.info(TAG, `connector started (pid ${child.pid})`);
+        const forward = (stream, level) => {
+            stream?.on('data', (chunk) => {
+                for (const line of chunk.toString().split('\n')) {
+                    if (line.trim())
+                        logger[level](TAG, `[connector] ${line}`);
+                }
+            });
+        };
+        forward(child.stdout, 'info');
+        forward(child.stderr, 'warn');
+        child.on('exit', (code, signal) => {
+            child = null;
+            if (stopped)
+                return;
+            const aliveMs = Date.now() - startedAt;
+            if (aliveMs >= STABLE_RESET_MS)
+                backoffMs = MIN_BACKOFF_MS;
+            // Exit is EXPECTED pre-token (the connector exits until the connect
+            // message is saved) — restart with backoff, exactly like systemd's
+            // Restart=always did.
+            logger.info(TAG, `connector exited (code=${code ?? 'null'} signal=${signal ?? 'null'} after ${Math.round(aliveMs / 1000)}s) — restarting in ${backoffMs / 1000}s`);
+            restartTimer = setTimeout(launch, backoffMs);
+            restartTimer.unref?.();
+            backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        });
+        child.on('error', (err) => {
+            logger.error(TAG, `connector spawn failed: ${err.message}`);
+            child = null;
+            if (stopped)
+                return;
+            restartTimer = setTimeout(launch, backoffMs);
+            restartTimer.unref?.();
+            backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
+        });
+    };
+    launch();
+    const handle = {
+        stop() {
+            stopped = true;
+            if (restartTimer)
+                clearTimeout(restartTimer);
+            if (child) {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            singleton = null;
+        },
+        isRunning() {
+            return child !== null;
+        },
+    };
+    singleton = handle;
+    return handle;
+}
+/** Test-only: reset the module singleton. */
+export function resetConnectorSupervisorForTest() {
+    singleton = null;
+}

package/assets/plugin/index.js

@@ -40,6 +40,7 @@ import { queryReviewOutcomesTool } from './tools/query-review-outcomes.js';
 import { loadPositionReviewMode } from './config/position-review-config.js';
 import { installSignalHandlers } from './lifecycle/install-signal-handlers.js';
 import { readPluginConfig } from './config/plugin-config-io.js';
+import { startConnectorSupervisor } from './connector-supervisor.js';
 import { ToolGate } from './config/tool-gate.js';
 import { gateStore } from './config/gate-store.js';
 import { startAgentConfigPoller } from './config/agent-config-poller.js';
@@ -861,6 +862,13 @@ const paperTradingPlugin = {
             if (pluginToolsFactory) {
                 api.registerTool(pluginToolsFactory, { names: pluginToolNames });
             }
+            // The supervisor must be (re)evaluated on EVERY register call, not just
+            // the first: the first full register can run BEFORE the installer has
+            // written connectorSupervisor='on' (the gateway hot-reloads the plugin
+            // the moment `plugins install --link` records it), and OpenClaw's
+            // in-process restart re-invokes register() down THIS early-return path.
+            // startConnectorSupervisor() is itself a singleton — repeat calls no-op.
+            maybeStartConnectorSupervisor();
             return;
         }
         logger.info(TAG, 'Initializing paper trading plugin...');
@@ -1984,6 +1992,31 @@ const paperTradingPlugin = {
         pluginToolNames = toolNames;
         pluginInitialised = true;
         logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
+        maybeStartConnectorSupervisor();
     },
 };
+/** Plugin-supervised connector (frictionless onboarding): when plugin-config
+ *  says connectorSupervisor='on' (written by the npx installer on fresh
+ *  installs — NEVER defaulted on, prod runs the bridge under systemd and
+ *  would double-connect the relay room), the plugin spawns + restarts the
+ *  relay connector as a child of the gateway process. OpenClaw is the process
+ *  manager: no systemd, works in containers, dies with the gateway.
+ *  Kill-switch: RC_CONNECTOR_SUPERVISOR=off. Called from EVERY register()
+ *  path (config may appear between calls); the supervisor itself is a
+ *  singleton so repeat calls no-op. */
+function maybeStartConnectorSupervisor() {
+    try {
+        const supervisorMode = readPluginConfig().connectorSupervisor;
+        if (process.env.RC_CONNECTOR_SUPERVISOR === 'off') {
+            if (supervisorMode === 'on')
+                logger.warn(TAG, 'connector supervisor disabled by RC_CONNECTOR_SUPERVISOR=off');
+        }
+        else if (supervisorMode === 'on') {
+            startConnectorSupervisor();
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `connector supervisor init failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
 export default paperTradingPlugin;

package/assets/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: reefclaw
-version: 0.0.1
+version: 0.0.2
 description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
 author: ReefClaw
 homepage: https://reefclaw.com
@@ -29,7 +29,7 @@ config:
      connect instructions. The FULL trading instructions (versioned 2.x.y) are
      delivered automatically by the ReefClaw connector minutes after the first
      successful connect, over the authenticated update channel — they replace
-     this file in place (version 0.0.1 always loses the semver comparison).
+     this file in place (a 0.0.x version always loses the semver comparison).
      The "Connecting (first run)" section below MUST stay in sync with the
      same section in skill/SKILL.md. -->
 
@@ -37,7 +37,7 @@ config:
 
 You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard. This bootstrap file only covers **connecting**; your full trading instructions arrive automatically a few minutes after the connection succeeds.
 
-**Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still the bootstrap version (0.0.1), the connection has not completed — finish connecting first.
+**Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
 
 ## Connecting (first run) — saving the connect message
 
@@ -66,8 +66,22 @@ When a user gives you this message (or just a bare `Here's my ReefClaw token: rc
 - After saving, the connector picks the config up within seconds (it restarts until a token appears). The user does not need to run any command.
 - If you cannot write the config yourself (e.g. exec or file access is restricted in this session), show the user this exact JSON snippet and where it goes, and offer to verify it after they save it.
 
+## If you cannot run the installer (elevated exec disabled)
+
+Fresh OpenClaw installs deny elevated (host) exec from chat sessions. If `npx @reefclaw/connect` is blocked, do NOT dead-end — offer the user this choice:
+
+1. **Self-service (no terminal)**:
+   - Add the user's **sender id** (visible in this session's context) to `tools.elevated.allowFrom.<this channel>` in `~/.openclaw/openclaw.json`. This is an **array of sender ids per provider** — e.g. `"tools": { "elevated": { "allowFrom": { "telegram": ["12345678"] } } }` — NOT a boolean.
+   - Tell the user to type `/restart` in this chat (OpenClaw's built-in in-process restart).
+   - Then the user types `/elevated full` — elevated exec is **per-session and off until the user activates it**; OpenClaw confirms with "Elevated mode set to full". If it replies that the sender is not on the allowlist, re-check the allowFrom shape.
+   - **RETRY the install command — do not assume it is still blocked.**
+   - After the install succeeds: the user types `/elevated off` and you remove the allowFrom entry (the installed system never needs elevated exec — only the install did).
+2. **Manual (last resort)**: the user runs `npx @reefclaw/connect` themselves in a terminal on this machine — one command, nothing else.
+
+Either way, **save the connection config regardless** — the connector picks it up automatically the moment the install completes.
+
 ## After connecting
 
 - The ReefClaw dashboard flips to **Connected** on its own — no manual verification step.
 - Your full trading instructions (SKILL.md version 2.x) are delivered automatically over the authenticated connection and replace this file. You will be notified in chat when that happens.
-- If more than ~10 minutes pass after a successful connect and this file is still version 0.0.1, tell the user to check the dashboard connection status.
+- If more than ~10 minutes pass after a successful connect and this file is still a 0.0.x bootstrap version, tell the user to check the dashboard connection status.

package/dist/cli.js

@@ -10,7 +10,7 @@
 import { installPlugin } from './plugin.js';
 import { installBridge } from './bridge.js';
 import { installSkill } from './skill.js';
-import { installDaemon } from './daemon.js';
+import { enableConnectorSupervisor } from './supervisor-config.js';
 import { checkGateway } from './validate.js';
 import { readConfig, writeConfig, mergeReefClawConfig, gatewayAuthDowngradeNeeded, openClawInstalled, openClawConfigPath, readGatewayPort, } from './openclaw.js';
 import { run, which } from './exec.js';
@@ -99,7 +99,10 @@ async function main() {
     // invalid config.
     const skill = installSkill();
     installBridge();
-    const startedService = installDaemon();
+    // The plugin (inside the gateway) supervises the connector — no systemd/
+    // launchd/Task-Scheduler, works in containers. The gateway restart below is
+    // therefore also what STARTS the connector.
+    const supervised = enableConnectorSupervisor();
     if (plugin.registered)
         restartGateway();
     await checkGateway(readGatewayPort(merged));
@@ -109,8 +112,8 @@ async function main() {
     if (!skill.installed) {
         warn('The agent skill was placed but not registered — see the message above to finish it.');
     }
-    if (!startedService) {
-        warn('The connector was installed but not auto-started — see the run command above.');
+    if (!supervised) {
+        warn('Connector supervision was not enabled — see the message above to finish it.');
     }
     nextSteps();
 }

package/dist/supervisor-config.js

@@ -0,0 +1,38 @@
+// Enable the plugin-supervised connector for this install: write
+// `connectorSupervisor: 'on'` into ~/.reefclaw/plugin-config.json. The plugin
+// (running inside the OpenClaw gateway) then spawns + restarts the connector
+// itself — OpenClaw is the process manager. No systemd, no launchd, no Task
+// Scheduler; works anywhere the gateway runs, including containers.
+//
+// Merge-preserving: the file may already exist (re-runs, or the operator's
+// dashboard wrote exchange credentials); unknown keys survive.
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { REEFCLAW_HOME } from './paths.js';
+import { step, ok, warn, info } from './ui.js';
+export function enableConnectorSupervisor() {
+    step('Handing connector supervision to OpenClaw');
+    const path = join(REEFCLAW_HOME, 'plugin-config.json');
+    try {
+        let cfg = {};
+        if (existsSync(path)) {
+            cfg = JSON.parse(readFileSync(path, 'utf-8'));
+        }
+        cfg.connectorSupervisor = 'on';
+        mkdirSync(REEFCLAW_HOME, { recursive: true, mode: 0o700 });
+        writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', { encoding: 'utf-8', mode: 0o600 });
+        try {
+            chmodSync(path, 0o600); // mode is ignored when the file already existed
+        }
+        catch {
+            /* best-effort on non-POSIX filesystems */
+        }
+        ok('OpenClaw will start and supervise the connector (no service manager needed)');
+        return true;
+    }
+    catch (err) {
+        warn(`could not write ${path}: ${err instanceof Error ? err.message : String(err)}`);
+        info(`Add { "connectorSupervisor": "on" } to it yourself, then restart OpenClaw.`);
+        return false;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {