bereach-openclaw 1.5.6 → 1.5.7

package/node_modules/@bereach/tools/src/definitions.ts

@@ -1289,6 +1289,11 @@ export const definitions: ToolDefinition[] = [
         dailyActionLimit: { type: "integer", minimum: 1, description: "Max actions per day." },
         dailyTarget: { type: "integer", minimum: 1, description: "Daily target goal (e.g. 50 leads/day). Set null to remove." },
         totalTarget: { type: "integer", minimum: 1, description: "Total campaign goal (e.g. 500 leads total). Auto-completes when reached. Set null to remove." },
+        handoverMode: {
+          type: "string",
+          enum: ["on_reply", "on_goal", "manual"],
+          description: "When agent hands over conversation to human. on_reply (default): stop autonomous outreach when contact replies. on_goal: keep replying until meeting booked or converted. manual: never auto-stop.",
+        },
         taskOverrides: {
           type: "object",
           description: "Per-task-type config overrides. Keys are task types (e.g. 'lead-gen-visit', 'lead-gen-qualify'). Values are config objects with: maxRunsPerDay, minIntervalMinutes, defaultBatchSize, maxCreditsPerRun.",

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach-openclaw",
   "name": "BeReach",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "description": "LinkedIn outreach automation — 75+ tools, hook-based enforcement, dynamic context",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bereach-openclaw",
-  "version": "1.5.6",
+  "version": "1.5.7",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {

package/src/commands/connector.ts

@@ -63,6 +63,14 @@ type TaskResult = {
 
 const MIN_POLL_MS = 5000;
 
+/** Thrown when API returns 401/403 - credentials are invalid, retrying won't help */
+export class AuthError extends Error {
+  constructor(public readonly statusCode: number, body: string) {
+    super(`Auth failed (HTTP ${statusCode}): ${body.slice(0, 200)}`);
+    this.name = "AuthError";
+  }
+}
+
 // ---------------------------------------------------------------------------
 // TaskResult extraction from OpenClaw agent output
 // ---------------------------------------------------------------------------
@@ -167,6 +175,9 @@ async function httpPost(url: string, body: unknown, headers: Record<string, stri
   });
   if (!res.ok) {
     const text = await res.text().catch(() => "");
+    if (res.status === 401 || res.status === 403) {
+      throw new AuthError(res.status, text);
+    }
     throw new Error(`HTTP ${res.status}: ${text.slice(0, 200)}`);
   }
   return res.json();
@@ -513,7 +524,7 @@ async function updateTaskStatus(
 }
 
 export type ConnectorStatus = {
-  state: "stopped" | "starting" | "running" | "stopping" | "error" | "disabled";
+  state: "stopped" | "starting" | "running" | "stopping" | "error" | "disabled" | "dormant";
   uptime: number;
   lastHeartbeat: number;
   currentTaskId: string | undefined;
@@ -524,16 +535,26 @@ export type ConnectorStatus = {
 
 export async function runConnectorLoop(
   config: ConnectorConfig,
-  options?: { signal?: AbortSignal },
+  options?: { signal?: AbortSignal; onHeartbeat?: () => void },
 ): Promise<void> {
   let pollInterval = config.pollIntervalMs;
   let currentTaskId: string | undefined;
   let consecutiveErrors = 0;
+  let consecutiveAuthErrors = 0;
   let totalTasksExecuted = 0;
   let webhookAvailable = false;
 
   const signal = options?.signal;
 
+  // Internal AbortController: links heartbeat + poll loops so either can abort both.
+  // When heartbeat detects auth failure → aborts internal → poll loop exits too.
+  // External signal (from ConnectorManager) is forwarded to internal.
+  const internalAbort = new AbortController();
+  const internalSignal = internalAbort.signal;
+  if (signal) {
+    signal.addEventListener("abort", () => internalAbort.abort(signal.reason), { once: true });
+  }
+
   console.log(`[connector] Starting connector loop`);
   console.log(`[connector] API: ${config.apiUrl}`);
   console.log(`[connector] Auth: ${config.apiKey ? "API key (Bearer)" : "connector token (legacy)"}`);
@@ -550,32 +571,47 @@ export async function runConnectorLoop(
 
   // Heartbeat runs independently - does NOT touch pollInterval or consecutiveErrors.
   // Otherwise it would neutralize exponential backoff during error recovery.
+  // Uses internalAbort so auth failures kill both heartbeat AND poll loops.
   let consecutiveHeartbeatFailures = 0;
+  let consecutiveHeartbeatAuthErrors = 0;
   const heartbeatLoop = async () => {
-    while (!signal?.aborted) {
+    let heartbeatIntervalMs = 30_000;
+    while (!internalSignal.aborted) {
       try {
         await heartbeat(config, currentTaskId);
         consecutiveHeartbeatFailures = 0;
+        consecutiveHeartbeatAuthErrors = 0;
+        heartbeatIntervalMs = 30_000;
+        options?.onHeartbeat?.();
       } catch (err) {
         consecutiveHeartbeatFailures++;
-        console.error(`[connector] Heartbeat failed (${consecutiveHeartbeatFailures}):`, err);
-        if (consecutiveHeartbeatFailures === 5) {
-          console.warn("[connector] WARNING: 5 consecutive heartbeat failures, API may be unreachable");
-        }
-        if (consecutiveHeartbeatFailures >= 10) {
-          console.error("[connector] FATAL: 10 heartbeat failures, aborting connector for restart");
-          // Throw to exit the heartbeat loop - ConnectorManager will restart us
-          throw new Error("Too many consecutive heartbeat failures");
+        if (err instanceof AuthError) {
+          consecutiveHeartbeatAuthErrors++;
+          console.error(`[connector] Heartbeat auth failed (${consecutiveHeartbeatAuthErrors}/3): ${err.message}`);
+          if (consecutiveHeartbeatAuthErrors >= 3) {
+            console.error("[connector] FATAL: 3 consecutive auth failures in heartbeat, API key is invalid");
+            internalAbort.abort(err);
+            return;
+          }
+        } else {
+          consecutiveHeartbeatAuthErrors = 0;
+          console.error(`[connector] Heartbeat failed (${consecutiveHeartbeatFailures}):`, err instanceof Error ? err.message : String(err));
+          if (consecutiveHeartbeatFailures === 5) {
+            console.warn("[connector] WARNING: 5 consecutive heartbeat failures, API may be unreachable");
+          }
+          // Exponential backoff: 30s → 60s → 120s → max 5min (never die for transient errors)
+          heartbeatIntervalMs = Math.min(heartbeatIntervalMs * 2, 5 * 60 * 1000);
         }
       }
       await new Promise((r) => {
-        const timer = setTimeout(r, 30_000);
-        signal?.addEventListener("abort", () => { clearTimeout(timer); r(undefined); }, { once: true });
+        const timer = setTimeout(r, heartbeatIntervalMs);
+        internalSignal.addEventListener("abort", () => { clearTimeout(timer); r(undefined); }, { once: true });
       });
     }
   };
   heartbeatLoop().catch((err) => {
     console.error("[connector] Heartbeat loop crashed:", err instanceof Error ? err.message : String(err));
+    if (!internalSignal.aborted) internalAbort.abort(err);
   });
 
   // Task execution lock - prevents concurrent task execution.
@@ -583,11 +619,11 @@ export async function runConnectorLoop(
   let isExecuting = false;
   let idlePollCount = 0;
 
-  while (!signal?.aborted) {
+  while (!internalSignal.aborted) {
     try {
       // Skip polling while a task is running - prevents claiming concurrent tasks
       if (isExecuting) {
-        await sleep(pollInterval, signal);
+        await sleep(pollInterval, internalSignal);
         continue;
       }
 
@@ -691,10 +727,22 @@ export async function runConnectorLoop(
       isExecuting = false;
       currentTaskId = undefined;
       (globalThis as any).__bereachCurrentTaskId = undefined;
-      console.error(
-        `[connector] Poll error (${consecutiveErrors}):`,
-        err,
-      );
+
+      if (err instanceof AuthError) {
+        consecutiveAuthErrors++;
+        console.error(`[connector] Poll auth failed (${consecutiveAuthErrors}/3): ${err.message}`);
+        if (consecutiveAuthErrors >= 3) {
+          console.error("[connector] FATAL: 3 consecutive auth failures in poll loop, API key is invalid");
+          internalAbort.abort(err);
+          break;
+        }
+      } else {
+        consecutiveAuthErrors = 0;
+        console.error(
+          `[connector] Poll error (${consecutiveErrors}):`,
+          err instanceof Error ? err.message : String(err),
+        );
+      }
 
       pollInterval = Math.min(
         config.pollIntervalMs * Math.pow(2, consecutiveErrors),
@@ -711,10 +759,17 @@ export async function runConnectorLoop(
       }
     }
 
-    await sleep(pollInterval, signal);
+    await sleep(pollInterval, internalSignal);
   }
 
   console.log("[connector] Loop stopped (abort signal received)");
+
+  // If internal abort fired (auth failure) but external didn't (not a graceful shutdown),
+  // throw so ConnectorManager.handleCrash() triggers with the auth error.
+  if (internalSignal.aborted && !signal?.aborted) {
+    const reason = internalSignal.reason;
+    throw reason instanceof Error ? reason : new Error("Connector loop aborted internally");
+  }
 }
 
 /** Re-probe webhook availability. Called by ConnectorManager on retry. */

package/src/connector/manager.ts

@@ -4,39 +4,75 @@
  * Auto-starts the polling loop from register() when an API key is present.
  * Handles crash recovery with exponential backoff, graceful shutdown on
  * SIGTERM/SIGINT, and prevents duplicate instances.
+ *
+ * Key resilience features:
+ * - AuthError detection: distinguishes auth failures from transient errors
+ * - Dormant mode: after persistent auth failures, enters low-power probe mode
+ *   instead of burning restarts. Probes every 15 min and auto-recovers.
+ * - Config resolver: re-resolves API key on each restart/probe
+ * - Health check: detects zombie state (running but heartbeat dead)
  */
 
-import { runConnectorLoop, isWebhookAvailable, type ConnectorConfig, type ConnectorStatus } from "../commands/connector.js";
+import { runConnectorLoop, isWebhookAvailable, AuthError, type ConnectorConfig, type ConnectorStatus } from "../commands/connector.js";
 
 const MAX_RESTARTS = 10;
 const INITIAL_RESTART_DELAY_MS = 1_000;
 const MAX_RESTART_DELAY_MS = 30_000;
+const DORMANT_PROBE_INTERVAL_MS = 15 * 60 * 1000; // 15 min
 
-export type ConnectorManagerState = "stopped" | "starting" | "running" | "stopping" | "error" | "disabled";
+export type ConnectorManagerState = "stopped" | "starting" | "running" | "stopping" | "error" | "disabled" | "dormant";
 
 class ConnectorManager {
   private state: ConnectorManagerState = "stopped";
   private abortController: AbortController | null = null;
   private config: ConnectorConfig | null = null;
+  private resolveConfig: (() => ConnectorConfig) | null = null;
   private restartCount = 0;
   private startedAt = 0;
   private lastHeartbeatAt = 0;
   private totalTasksExecuted = 0;
   private consecutiveErrors = 0;
+  private consecutiveAuthCrashes = 0;
   private executionMode: "webhook" | "execFile" = "execFile";
   private loopPromise: Promise<void> | null = null;
   private signalHandlersInstalled = false;
+  private stabilityTimer: ReturnType<typeof setTimeout> | null = null;
+  private dormantTimer: ReturnType<typeof setTimeout> | null = null;
 
   /**
-   * Start the connector. Idempotent - if already running, logs and returns.
+   * Start the connector. Accepts either a static config or a resolver function
+   * that re-resolves config (including API key) on each restart.
+   *
+   * Idempotent with smart recovery:
+   * - If dormant: wakes up and attempts restart (user may have changed key)
+   * - If running but unhealthy: forces restart
+   * - If running and healthy: skips
    */
-  async start(config: ConnectorConfig): Promise<void> {
-    if (this.state === "running" || this.state === "starting") {
-      console.log("[bereach:connector] skip duplicate start (already running)");
-      return;
+  async start(configOrResolver: ConnectorConfig | (() => ConnectorConfig)): Promise<void> {
+    // Store resolver for future re-resolution
+    if (typeof configOrResolver === "function") {
+      this.resolveConfig = configOrResolver;
+      this.config = configOrResolver();
+    } else {
+      this.resolveConfig = null;
+      this.config = configOrResolver;
+    }
+
+    if (this.state === "dormant") {
+      // User may have changed their key - wake up and try
+      console.log("[bereach:connector] waking from dormant mode (register() called)");
+      if (this.dormantTimer) { clearTimeout(this.dormantTimer); this.dormantTimer = null; }
+      this.consecutiveAuthCrashes = 0;
+      // Fall through to normal start
+    } else if (this.state === "running" || this.state === "starting") {
+      if (this.isHealthy()) {
+        console.log("[bereach:connector] skip duplicate start (already running and healthy)");
+        return;
+      }
+      console.warn("[bereach:connector] connector unhealthy, forcing restart");
+      await this.stop();
     }
 
-    this.config = config;
     this.state = "starting";
     this.restartCount = 0;
 
@@ -73,11 +109,11 @@ class ConnectorManager {
       process.on("SIGINT", () => shutdown("SIGINT"));
     }
 
-    // Probe webhook availability with retry — the gateway HTTP server may not be
+    // Probe webhook availability with retry - the gateway HTTP server may not be
     // listening yet when register() fires during plugin load.
     let webhookOk = false;
     for (let attempt = 1; attempt <= 5; attempt++) {
-      webhookOk = await isWebhookAvailable(config);
+      webhookOk = await isWebhookAvailable(this.config);
       if (webhookOk) break;
       if (attempt < 5) {
         console.log(`[bereach:connector] webhook probe attempt ${attempt}/5 failed, retrying in 3s...`);
@@ -95,6 +131,9 @@ class ConnectorManager {
   async stop(): Promise<void> {
     if (this.state === "stopped" || this.state === "disabled") return;
 
+    // Clean up dormant timer if active
+    if (this.dormantTimer) { clearTimeout(this.dormantTimer); this.dormantTimer = null; }
+
     this.state = "stopping";
     console.log("[bereach:connector] stopping...");
 
@@ -128,10 +167,43 @@ class ConnectorManager {
     };
   }
 
-  private stabilityTimer: ReturnType<typeof setTimeout> | null = null;
+  /**
+   * Check if the connector is actually healthy (not a zombie).
+   * Unhealthy = running state but no heartbeat in 5+ minutes,
+   * or running for 2+ minutes without ever getting a heartbeat.
+   */
+  private isHealthy(): boolean {
+    if (this.state !== "running") return false;
+    const now = Date.now();
+    const uptime = now - this.startedAt;
+    // Just started (< 2 min), give it time
+    if (uptime < 2 * 60 * 1000) return true;
+    // No heartbeat ever received after 2 min = zombie
+    if (!this.lastHeartbeatAt) return false;
+    // Last heartbeat > 5 min ago = zombie
+    return (now - this.lastHeartbeatAt) < 5 * 60 * 1000;
+  }
+
+  /**
+   * Re-resolve config from the resolver (picks up API key changes).
+   * Falls back to stored config if no resolver.
+   */
+  private freshConfig(): ConnectorConfig | null {
+    if (this.resolveConfig) {
+      try {
+        this.config = this.resolveConfig();
+        const masked = this.config.apiKey ? `...${this.config.apiKey.slice(-6)}` : "NOT SET";
+        console.log(`[bereach:connector] re-resolved config (API key: ${masked})`);
+      } catch (err) {
+        console.error("[bereach:connector] config resolver failed:", err instanceof Error ? err.message : String(err));
+      }
+    }
+    return this.config;
+  }
 
   private startLoop(): void {
-    if (!this.config) return;
+    const config = this.freshConfig();
+    if (!config) return;
 
     this.abortController = new AbortController();
     this.startedAt = Date.now();
@@ -151,7 +223,10 @@ class ConnectorManager {
     }, 5 * 60 * 1000);
     this.stabilityTimer.unref();
 
-    this.loopPromise = runConnectorLoop(this.config, { signal: this.abortController.signal })
+    this.loopPromise = runConnectorLoop(config, {
+      signal: this.abortController.signal,
+      onHeartbeat: () => { this.lastHeartbeatAt = Date.now(); },
+    })
       .then(() => {
         // Normal exit (abort signal)
         if (this.state !== "stopping") {
@@ -160,14 +235,29 @@ class ConnectorManager {
       })
       .catch((err) => {
         console.error(`[bereach:connector] loop crashed: ${err instanceof Error ? err.message : String(err)}`);
-        this.handleCrash();
+        this.handleCrash(err);
       });
   }
 
-  private handleCrash(): void {
+  private handleCrash(err?: unknown): void {
     this.restartCount++;
     this.consecutiveErrors++;
 
+    // Track consecutive auth-related crashes for dormant mode.
+    // 2 auth crashes = 2 full start→3-failures→crash cycles = ~6 total 401s.
+    const isAuthCrash = err instanceof AuthError ||
+      (err instanceof Error && err.message.includes("Auth failed"));
+    if (isAuthCrash) {
+      this.consecutiveAuthCrashes++;
+      console.error(`[bereach:connector] auth crash ${this.consecutiveAuthCrashes}/2`);
+      if (this.consecutiveAuthCrashes >= 2) {
+        this.enterDormant();
+        return;
+      }
+    } else {
+      this.consecutiveAuthCrashes = 0;
+    }
+
     if (this.restartCount > MAX_RESTARTS) {
       // Don't give up permanently - enter cooldown then restart.
       // The user's VPS has no supervisor to restart us, so we must self-recover.
@@ -199,6 +289,69 @@ class ConnectorManager {
       this.startLoop();
     }, delay);
   }
+
+  /**
+   * Enter dormant mode - lightweight 15-min probe instead of full restart loop.
+   * Used when API key is confirmed invalid (persistent auth failures).
+   * Auto-recovers when the key becomes valid again.
+   */
+  private enterDormant(): void {
+    this.state = "dormant";
+    this.abortController = null;
+    this.loopPromise = null;
+    console.error(
+      "[bereach:connector] API key invalid - entering dormant mode. " +
+      "Will probe every 15 min and auto-recover when key is fixed.",
+    );
+    this.scheduleDormantProbe();
+  }
+
+  private scheduleDormantProbe(): void {
+    if (this.dormantTimer) clearTimeout(this.dormantTimer);
+    this.dormantTimer = setTimeout(() => this.runDormantProbe(), DORMANT_PROBE_INTERVAL_MS);
+    this.dormantTimer.unref();
+  }
+
+  private async runDormantProbe(): Promise<void> {
+    if (this.state !== "dormant") return;
+
+    // Re-resolve config to pick up any key changes
+    const config = this.freshConfig();
+    if (!config?.apiKey) {
+      console.log("[bereach:connector] dormant probe: no API key configured, will retry in 15 min");
+      this.scheduleDormantProbe();
+      return;
+    }
+
+    // Single lightweight heartbeat probe
+    try {
+      const res = await fetch(`${config.apiUrl}/connectors/heartbeat`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok) {
+        console.log("[bereach:connector] dormant probe succeeded! Restarting connector.");
+        this.consecutiveAuthCrashes = 0;
+        this.restartCount = 0;
+        this.consecutiveErrors = 0;
+        this.startLoop();
+        return;
+      }
+      if (res.status === 401 || res.status === 403) {
+        console.log("[bereach:connector] dormant probe: still 401, will retry in 15 min");
+      } else {
+        console.log(`[bereach:connector] dormant probe: HTTP ${res.status}, will retry in 15 min`);
+      }
+    } catch (err) {
+      console.log(`[bereach:connector] dormant probe failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    this.scheduleDormantProbe();
+  }
 }
 
 // Module-level singleton

package/src/index.ts

@@ -232,14 +232,14 @@ export default function register(api: any) {
     const gatewayUrl = config.gatewayUrl || readEnv("OPENCLAW_GATEWAY_URL") || "http://localhost:18789";
     const pollMs = config.connectorPollIntervalMs ?? 15000;
 
-    connectorManager.start({
-      apiKey,
+    connectorManager.start(() => ({
+      apiKey: resolveApiKey(api),
       apiUrl: API_BASE,
       openclawUrl: readEnv("OPENCLAW_URL") || "http://localhost:3579",
       pollIntervalMs: Math.max(5000, pollMs),
       gatewayUrl,
       hooksToken,
-    }).catch((err) => {
+    })).catch((err) => {
       log(`connector auto-start failed: ${err instanceof Error ? err.message : String(err)}`);
     });
   } else if (!connectorEnabled) {