@reefclaw/connect 0.1.2 → 0.1.4

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,36 @@
+import { spawn } from 'node:child_process';
+/** Bridge bundled INSIDE the plugin package (the npm-channel distribution
+ *  `@reefclaw/openclaw-plugin` ships the connector at <pluginRoot>/bridge).
+ *  Compiled connector-supervisor.js sits at the plugin dist root, so the
+ *  bundled bridge is a sibling directory. */
+export declare function bundledBridgeDir(): string;
+/** Where the connector lives, in preference order: bundled-in-package first
+ *  (npm-channel install — self-contained), then the npx installer's
+ *  placement. Returns null when neither exists. */
+export declare function resolveBridgeDir(): string | null;
+/** True when the plugin should supervise the connector even WITHOUT an
+ *  explicit connectorSupervisor='on' in plugin-config: the connector is
+ *  bundled inside this plugin package, which only the npm-channel
+ *  distribution does. Prod's linked plugin dir and the npx installer's
+ *  ~/.reefclaw/plugin have no bridge/ subdir, so they stay opt-in — prod
+ *  keeps running the bridge under systemd and must never double-connect. */
+export declare function hasBundledBridge(): boolean;
+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,149 @@
+// 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, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger } from './logger.js';
+const TAG = 'connector-supervisor';
+/** Bridge bundled INSIDE the plugin package (the npm-channel distribution
+ *  `@reefclaw/openclaw-plugin` ships the connector at <pluginRoot>/bridge).
+ *  Compiled connector-supervisor.js sits at the plugin dist root, so the
+ *  bundled bridge is a sibling directory. */
+export function bundledBridgeDir() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'bridge');
+}
+/** Where the connector lives, in preference order: bundled-in-package first
+ *  (npm-channel install — self-contained), then the npx installer's
+ *  placement. Returns null when neither exists. */
+export function resolveBridgeDir() {
+    for (const dir of [bundledBridgeDir(), join(homedir(), '.reefclaw', 'bridge')]) {
+        if (existsSync(join(dir, 'index.js')))
+            return dir;
+    }
+    return null;
+}
+/** True when the plugin should supervise the connector even WITHOUT an
+ *  explicit connectorSupervisor='on' in plugin-config: the connector is
+ *  bundled inside this plugin package, which only the npm-channel
+ *  distribution does. Prod's linked plugin dir and the npx installer's
+ *  ~/.reefclaw/plugin have no bridge/ subdir, so they stay opt-in — prod
+ *  keeps running the bridge under systemd and must never double-connect. */
+export function hasBundledBridge() {
+    return existsSync(join(bundledBridgeDir(), 'index.js'));
+}
+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 ?? resolveBridgeDir();
+    if (!bridgeDir) {
+        logger.warn(TAG, 'connector not found (no bundled bridge/ and no ~/.reefclaw/bridge) — supervisor idle');
+        return null;
+    }
+    const indexJs = join(bridgeDir, 'index.js');
+    if (!existsSync(indexJs)) {
+        logger.warn(TAG, `connector not found at ${indexJs} — supervisor idle`);
+        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, hasBundledBridge } 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,39 @@ 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');
+            return;
+        }
+        if (supervisorMode === 'off')
+            return;
+        // 'on' → explicit opt-in (the npx installer writes this).
+        // undefined → auto-start ONLY when the connector is bundled inside this
+        // plugin package (the npm-channel @reefclaw/openclaw-plugin distribution
+        // is self-contained by design). Prod's linked plugin dir has no bundled
+        // bridge and no flag → stays off; systemd keeps owning prod's bridge.
+        if (supervisorMode === 'on' || hasBundledBridge()) {
+            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.2
+version: 0.0.3
 description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
 author: ReefClaw
 homepage: https://reefclaw.com
@@ -66,6 +66,16 @@ 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.
 
+## Installing without any terminal (preferred)
+
+OpenClaw can install the ReefClaw plugin through its own owner chat command — no exec, no terminal:
+
+1. In `~/.openclaw/openclaw.json` set `commands.plugins: true` and add the user's **sender id** (visible in this session) to `commands.ownerAllowFrom`.
+2. Tell the user to type `/restart` in this chat.
+3. Then the user types: `/plugins install npm:@reefclaw/openclaw-plugin` — the install restarts OpenClaw automatically; the bundled connector starts by itself and the dashboard flips to Connected.
+
+Only fall back to `npx @reefclaw/connect` (below) when the chat install is unavailable.
+
 ## 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:

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.4",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {