@reefclaw/connect 0.1.2 → 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/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.2",
+  "version": "0.1.3",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {