bereach-openclaw 1.5.6 → 1.5.8

package/node_modules/@bereach/tools/src/cache-types.ts

@@ -102,4 +102,6 @@ export interface CacheStore {
   sessionMeta: SessionMeta | null;
   onboardingState: OnboardingState | null;
   recentEvents: RecentEvent[];
+  /** LLM circuit breaker status: "auth" | "billing" | "error" when tripped, null when OK */
+  llmStatus?: string | null;
 }

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.",
@@ -1302,6 +1307,11 @@ export const definitions: ToolDefinition[] = [
             },
           },
         },
+        disabledTaskTypes: {
+          type: "array",
+          items: { type: "string" },
+          description: "Task types to stop dispatching for this campaign (e.g. ['lead-gen-discovery']). Use when strategically pausing a task type (low conversion, enough leads). Set to [] to re-enable all.",
+        },
       },
     },
   },

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach-openclaw",
   "name": "BeReach",
-  "version": "1.5.6",
+  "version": "1.5.8",
   "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.8",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {

package/src/commands/connector.ts

@@ -59,10 +59,27 @@ type TaskResult = {
   invitationsAccepted?: number;
   error?: string;
   reason?: string;
+  // Token usage tracking
+  tokenUsage?: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+  };
+  estimatedCostUsd?: number;
+  model?: string;
 };
 
 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
 // ---------------------------------------------------------------------------
@@ -123,6 +140,98 @@ function extractTaskResultFromWrapper(output: Record<string, unknown>): TaskResu
   return null;
 }
 
+/**
+ * Extract token usage from the OpenClaw --json wrapper's meta field.
+ * Returns null if no usage data is available.
+ */
+function extractTokenUsageFromWrapper(
+  output: Record<string, unknown>,
+): { usage: TaskResult["tokenUsage"]; model?: string } | null {
+  const result = output?.result as Record<string, unknown> | undefined;
+  const meta = (result?.meta ?? output?.meta ?? {}) as Record<string, unknown>;
+  // OpenClaw 2026.4+ puts token data in meta.agentMeta.lastCallUsage
+  const agentMeta = (meta.agentMeta ?? {}) as Record<string, unknown>;
+  const lastCall = (agentMeta.lastCallUsage ?? {}) as Record<string, number>;
+  const costData = (meta.cost ?? {}) as Record<string, number>;
+  const usageData = (meta.usage ?? {}) as Record<string, number>;
+
+  const inputTokens = lastCall.input ?? costData.inputTokens ?? costData.input ?? usageData.input ?? 0;
+  const outputTokens = lastCall.output ?? costData.outputTokens ?? costData.output ?? usageData.output ?? 0;
+
+  if (inputTokens === 0 && outputTokens === 0) return null;
+
+  const cacheRead = lastCall.cacheRead ?? usageData.cacheRead ?? costData.cacheReadTokens ?? 0;
+  const cacheWrite = lastCall.cacheWrite ?? usageData.cacheWrite ?? costData.cacheWriteTokens ?? 0;
+
+  return {
+    usage: {
+      inputTokens,
+      outputTokens,
+      ...(cacheRead > 0 ? { cacheReadTokens: cacheRead } : {}),
+      ...(cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {}),
+    },
+    model: agentMeta.model as string | undefined,
+  };
+}
+
+/** Model pricing per 1M tokens */
+const MODEL_PRICING: Record<string, { input: number; output: number; cacheRead: number }> = {
+  "haiku": { input: 1.0, output: 5.0, cacheRead: 0.1 },
+  "sonnet": { input: 3.0, output: 15.0, cacheRead: 0.3 },
+  "flash": { input: 0.3, output: 2.5, cacheRead: 0.03 },
+  "pro": { input: 1.25, output: 10.0, cacheRead: 0.125 },
+};
+
+function estimateTaskCost(
+  usage: NonNullable<TaskResult["tokenUsage"]>,
+  modelSlug?: string | null,
+): number {
+  const key = Object.keys(MODEL_PRICING).find((k) => modelSlug?.includes(k)) ?? "haiku";
+  const p = MODEL_PRICING[key];
+  const cached = usage.cacheReadTokens ?? 0;
+  const uncached = Math.max(0, usage.inputTokens - cached);
+  return (uncached * p.input + cached * p.cacheRead + usage.outputTokens * p.output) / 1_000_000;
+}
+
+/** Enrich a TaskResult with token usage from the OpenClaw wrapper output */
+function enrichResultWithTokens(
+  result: TaskResult,
+  output: Record<string, unknown>,
+  modelSlug?: string | null,
+): void {
+  if (result.tokenUsage) return; // already enriched (e.g. by lifecycle hook)
+  const extracted = extractTokenUsageFromWrapper(output);
+  if (!extracted?.usage) return;
+  const effectiveModel = extracted.model ?? modelSlug ?? undefined;
+  result.tokenUsage = extracted.usage;
+  result.model = effectiveModel;
+  result.estimatedCostUsd = estimateTaskCost(extracted.usage, effectiveModel);
+  console.log(
+    `[connector] Token usage: input=${extracted.usage.inputTokens} output=${extracted.usage.outputTokens}` +
+    ` cacheRead=${extracted.usage.cacheReadTokens ?? 0} cost=$${result.estimatedCostUsd.toFixed(4)}` +
+    ` model=${effectiveModel ?? "unknown"}`,
+  );
+}
+
+// LLM provider error detection — mirrors apps/web/src/lib/errors/llm-errors.ts
+// but self-contained since plugin can't import from apps/web.
+const LLM_ERROR_PATTERNS = [
+  /authentication_error/i, /invalid.*api.?key/i, /permission_error/i,
+  /401.*unauthorized/i, /access_denied.*api/i, /unauthorized.*invalid/i,
+  /out of (extra )?usage/i, /insufficient.quota/i, /exceeded.*current quota/i,
+  /RESOURCE_EXHAUSTED/i, /credit balance.*too low/i, /exceeded.*spending.*limit/i,
+  /billing.*hard.*limit/i, /payment.*required/i,
+];
+
+/** Scan text for LLM provider errors (auth, billing). Returns the matched text or null. */
+function detectLlmError(text: string): string | null {
+  for (const pattern of LLM_ERROR_PATTERNS) {
+    const match = text.match(pattern);
+    if (match) return match[0];
+  }
+  return null;
+}
+
 /** Stderr patterns that are noise (module warnings, not actual errors) */
 const HARMLESS_STDERR_RE = [
   /Cannot find module '@aws-sdk\/client-bedrock'/,
@@ -167,6 +276,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();
@@ -337,8 +449,11 @@ async function executeViaWebhook(
 
     // Webhook completed - lifecycle hook has already posted the result.
     // Return a success indicator so the connector doesn't double-report.
+    // Also extract token usage for the safety-net submission.
+    const webhookResult = (output.result as TaskResult) ?? { success: true };
+    enrichResultWithTokens(webhookResult, output, task.model);
     return {
-      result: (output.result as TaskResult) ?? { success: true },
+      result: webhookResult,
       error: null,
     };
   } catch (err) {
@@ -419,20 +534,25 @@ async function executeViaExecFile(
       // B17 fix: extract it instead of returning the raw wrapper.
       const extracted = extractTaskResultFromWrapper(output);
       if (extracted) {
+        enrichResultWithTokens(extracted, output, task.model);
         return { result: extracted, error: null };
       }
 
       // Fallback: if output itself looks like a flat TaskResult
       if (output.success !== undefined || output.contactsProcessed !== undefined) {
-        return { result: output as TaskResult, error: null };
+        const flat = output as unknown as TaskResult;
+        enrichResultWithTokens(flat, output, task.model);
+        return { result: flat, error: null };
       }
 
-      // Last resort: lifecycle hook may have already posted the real result
-      return { result: { success: true }, error: null };
+      // Last resort: lifecycle hook may have already posted the real result.
+      // Don't blindly claim success — if we can't parse a result, something went wrong.
+      // The lifecycle hook will report the real result if it ran successfully.
+      return { result: { success: false, reason: "no_parseable_result" } as unknown as TaskResult, error: null };
     } catch {
-      // Non-JSON output - treat as success if process exited cleanly
+      // Non-JSON output - can't determine success without structured data.
       return {
-        result: { success: true },
+        result: { success: false, reason: "non_json_output" } as unknown as TaskResult,
         error: null,
       };
     }
@@ -455,11 +575,14 @@ async function executeViaExecFile(
         // B17 fix: extract TaskResult from OpenClaw wrapper (same as happy path)
         const extracted = extractTaskResultFromWrapper(output);
         if (extracted) {
+          enrichResultWithTokens(extracted, output, task.model);
           return { result: extracted, error: null };
         }
         // Accept flat { success: true } format
         if (output.success !== undefined || output.contactsProcessed !== undefined) {
-          return { result: output as TaskResult, error: null };
+          const flat = output as unknown as TaskResult;
+          enrichResultWithTokens(flat, output, task.model);
+          return { result: flat, error: null };
         }
       } catch {
         // Not JSON
@@ -468,8 +591,20 @@ async function executeViaExecFile(
 
     // Filter known-harmless stderr noise (e.g. @aws-sdk/client-bedrock module warnings)
     const filtered = filterStderr(stderr);
-    const message = filtered || execErr.message || String(err);
-    return { result: null, error: message.slice(0, 500) };
+    // When execFile fails, err.message is "Command failed: openclaw agent ..." which is useless.
+    // Prefer stderr content, then stdout snippet, then exit code - anything more useful than the command string.
+    let errorMsg: string;
+    if (filtered) {
+      errorMsg = filtered;
+    } else if (execErr.message && !execErr.message.startsWith("Command failed:")) {
+      errorMsg = execErr.message;
+    } else {
+      // No stderr, message is just the command - build a useful error from what we have
+      const exitCode = execErr.code ?? "unknown";
+      const stdoutSnippet = stdout ? ` stdout=${stdout.slice(0, 200)}` : "";
+      errorMsg = `Agent process exited with code ${exitCode}${stdoutSnippet}`;
+    }
+    return { result: null, error: errorMsg.slice(0, 500) };
   }
 }
 
@@ -513,7 +648,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 +659,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)"}`);
@@ -548,34 +693,105 @@ export async function runConnectorLoop(
     console.log(`[connector] OpenClaw: ${config.openclawUrl}`);
   }
 
+  // Proactive LLM key validation on startup: detect bad API keys before wasting tasks.
+  // Makes a lightweight check against the LLM provider. Non-fatal — just warns.
+  const llmModel = readEnv("OPENCLAW_DEFAULT_MODEL") || readEnv("BEREACH_TASK_MODEL");
+  if (llmModel) {
+    const isAnthropic = llmModel.includes("anthropic") || llmModel.includes("claude");
+    const isGemini = llmModel.includes("gemini") || llmModel.includes("google");
+    const anthropicKey = readEnv("ANTHROPIC_API_KEY");
+    const geminiKey = readEnv("GEMINI_API_KEY") || readEnv("GOOGLE_API_KEY");
+
+    if (isAnthropic && anthropicKey) {
+      try {
+        const res = await fetch("https://api.anthropic.com/v1/messages", {
+          method: "POST",
+          headers: {
+            "x-api-key": anthropicKey,
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ model: "claude-haiku-4-5-20241022", max_tokens: 1, messages: [{ role: "user", content: "hi" }] }),
+          signal: AbortSignal.timeout(10000),
+        });
+        if (res.status === 401 || res.status === 403) {
+          const body = await res.text().catch(() => "");
+          console.error(`[connector] ANTHROPIC_API_KEY is INVALID (HTTP ${res.status}): ${body.slice(0, 200)}`);
+          console.error("[connector] Tasks will fail until the API key is updated. Reporting to BeReach API...");
+          // Report the error to BeReach API so the circuit breaker can trip
+          try {
+            await fetch(`${config.apiUrl}/connectors/heartbeat`, {
+              method: "POST",
+              headers: buildHeaders(config),
+              body: JSON.stringify({ llmKeyError: { provider: "anthropic", status: res.status, error: body.slice(0, 200) } }),
+              signal: AbortSignal.timeout(5000),
+            });
+          } catch { /* best effort */ }
+        } else {
+          console.log(`[connector] Anthropic API key validated (HTTP ${res.status})`);
+        }
+      } catch (err) {
+        console.warn(`[connector] Anthropic key validation failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    } else if (isGemini && geminiKey) {
+      try {
+        const res = await fetch(`https://generativelanguage.googleapis.com/v1/models?key=${geminiKey}`, {
+          signal: AbortSignal.timeout(10000),
+        });
+        if (res.status === 401 || res.status === 403) {
+          console.error(`[connector] GEMINI_API_KEY is INVALID (HTTP ${res.status})`);
+        } else {
+          console.log(`[connector] Gemini API key validated (HTTP ${res.status})`);
+        }
+      } catch (err) {
+        console.warn(`[connector] Gemini key validation failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+  }
+
   // 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 +799,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;
       }
 
@@ -664,6 +880,17 @@ export async function runConnectorLoop(
             console.warn(`[connector] DIAGNOSTIC: Task ${task.id} failed in <10s with 0 tool calls — likely context injection failure or model error`);
           }
 
+          // Scan output for LLM provider errors (auth/billing) that the gateway
+          // may not have flagged via meta.stopReason. If found, force-fail the task
+          // so the circuit breaker can detect it on the API side.
+          const allText = [error, result?.error, (result as any)?.reason].filter(Boolean).join(" ");
+          const llmError = detectLlmError(allText);
+          if (llmError && result && result.success !== false) {
+            console.warn(`[connector] LLM provider error detected in task ${task.id}: ${llmError}`);
+            result.success = false;
+            if (!result.error) result.error = `LLM provider error: ${llmError}`;
+          }
+
           // Always submit from connector as safety net. In webhook mode the lifecycle
           // hook usually reports first, but if it fails silently (network, crash) the
           // result is lost and the task stays "running" forever. The result endpoint
@@ -691,10 +918,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 +950,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/hooks/cache.ts

@@ -176,6 +176,7 @@ export async function fetchSnapshot(apiKey: string): Promise<CacheStore> {
     sessionMeta: snapshot.sessionMeta ?? null,
     onboardingState: snapshot.onboardingState ?? null,
     recentEvents: snapshot.recentEvents ?? [],
+    llmStatus: snapshot.llmStatus ?? null,
   };
 
   // Fallback: if snapshot didn't include limits, fetch from dedicated endpoint

package/src/hooks/context.ts

@@ -584,6 +584,21 @@ function formatLiveStatus(state: SessionState, data: CacheStore, apiKey?: string
 
   // ── ACTIVE MODE: data-only context for onboarded users ──
 
+  // LLM provider error warning — show prominently so the agent can inform the user
+  if (data.llmStatus) {
+    lines.push("### AI Provider Error");
+    if (data.llmStatus === "auth") {
+      lines.push("Your AI provider credentials are INVALID. Automated campaigns are paused.");
+      lines.push("Tell the user to update their API key in their provider's dashboard.");
+    } else if (data.llmStatus === "billing") {
+      lines.push("Your AI provider credits are EXHAUSTED. Automated campaigns are paused.");
+      lines.push("Tell the user to add credits or upgrade their plan with their AI provider.");
+    } else {
+      lines.push("There is an issue with the AI provider. Automated campaigns may be paused.");
+    }
+    lines.push("");
+  }
+
   // Account
   if (data.activeAccount) {
     const a = data.activeAccount;

package/src/hooks/enforcement.ts

@@ -318,9 +318,15 @@ function createDmGuard() {
 async function guardScheduledDm(toolName: string, params: Record<string, unknown>, key: string, state: SessionState) {
   if (toolName !== "bereach_scheduled_message_create") return null;
 
-  // DM history check
+  // DM history check — skip in task mode when prefetch already loaded conversation
+  // data server-side. The agent is instructed to skip tool calls when prefetch is
+  // present, so dmHistoryChecked will be empty. This is safe because:
+  // 1. Prefetch runs the same dedup check server-side before injecting data
+  // 2. Drafts (default status) are user-reviewed before sending
+  const isDraft = !params.status || params.status === "draft";
+  const isTaskMode = !!state.currentTaskMode;
   const dmId = extractDmIdentifier(params);
-  if (dmId && !state.dmHistoryChecked.has(dmId)) {
+  if (dmId && !state.dmHistoryChecked.has(dmId) && !(isTaskMode && isDraft)) {
     log(`scheduled DM dedup BLOCKED: history not checked for ${dmId}`);
     return {
       blocked: true,

package/src/hooks/lifecycle.ts

@@ -65,6 +65,82 @@ function parseStructuredResult(text: string): Record<string, unknown> | null {
 /** Exported for tests. */
 export { parseStructuredResult as _parseStructuredResult };
 
+// ---------------------------------------------------------------------------
+// Token usage extraction & cost estimation
+// ---------------------------------------------------------------------------
+
+/** Model pricing per 1M tokens (hardcoded — plugin can't import from apps/web) */
+const MODEL_PRICING: Record<string, { input: number; output: number; cacheRead: number }> = {
+  "haiku": { input: 1.0, output: 5.0, cacheRead: 0.1 },
+  "sonnet": { input: 3.0, output: 15.0, cacheRead: 0.3 },
+  "flash": { input: 0.3, output: 2.5, cacheRead: 0.03 },
+  "pro": { input: 1.25, output: 10.0, cacheRead: 0.125 },
+};
+
+function estimateTaskCost(
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens: number,
+  modelSlug?: string,
+): number {
+  const key = Object.keys(MODEL_PRICING).find((k) => modelSlug?.includes(k)) ?? "haiku";
+  const p = MODEL_PRICING[key];
+  const uncached = Math.max(0, inputTokens - cacheReadTokens);
+  return (uncached * p.input + cacheReadTokens * p.cacheRead + outputTokens * p.output) / 1_000_000;
+}
+
+/**
+ * Enrich a task result with token usage and cost estimation from OpenClaw's
+ * endCtx.meta. The meta object may contain:
+ *   - meta.cost: { inputTokens, outputTokens } (preferred)
+ *   - meta.usage: { input, output, cacheRead, cacheWrite } (alternative)
+ */
+function enrichWithTokenUsage(
+  taskResult: Record<string, unknown>,
+  endCtx: unknown,
+  taskMode: TaskModeInfo,
+): void {
+  try {
+    const meta = (endCtx as any)?.meta ?? (endCtx as any)?.result?.meta ?? {};
+    // OpenClaw provides token data in multiple possible locations:
+    // - meta.agentMeta.lastCallUsage (OpenClaw 2026.4+)
+    // - meta.cost (older versions / test runner)
+    // - meta.usage (alternative format)
+    const agentMeta = meta.agentMeta ?? {};
+    const lastCall = agentMeta.lastCallUsage ?? {};
+    const costData = meta.cost ?? {};
+    const usageData = meta.usage ?? {};
+
+    const inputTokens = lastCall.input ?? costData.inputTokens ?? costData.input ?? usageData.input ?? 0;
+    const outputTokens = lastCall.output ?? costData.outputTokens ?? costData.output ?? usageData.output ?? 0;
+
+    // No token data available — skip enrichment
+    if (inputTokens === 0 && outputTokens === 0) {
+      log(`token usage: no data in endCtx.meta for ${taskMode.taskId} (keys: ${Object.keys(meta).join(",")})`);
+      return;
+    }
+
+    const cacheRead = lastCall.cacheRead ?? usageData.cacheRead ?? costData.cacheReadTokens ?? 0;
+    const cacheWrite = lastCall.cacheWrite ?? usageData.cacheWrite ?? costData.cacheWriteTokens ?? 0;
+
+    taskResult.tokenUsage = {
+      inputTokens,
+      outputTokens,
+      ...(cacheRead > 0 ? { cacheReadTokens: cacheRead } : {}),
+      ...(cacheWrite > 0 ? { cacheWriteTokens: cacheWrite } : {}),
+    };
+
+    // Model slug from agentMeta (most reliable), env, or task mode
+    const modelSlug = agentMeta.model ?? readEnv("BEREACH_TASK_MODEL") ?? readEnv("OPENCLAW_MODEL") ?? undefined;
+    taskResult.model = modelSlug;
+    taskResult.estimatedCostUsd = estimateTaskCost(inputTokens, outputTokens, cacheRead, modelSlug);
+
+    log(`token usage for ${taskMode.taskId}: input=${inputTokens} output=${outputTokens} cacheRead=${cacheRead} cacheWrite=${cacheWrite} cost=$${(taskResult.estimatedCostUsd as number).toFixed(4)} model=${modelSlug ?? "unknown"}`);
+  } catch (err) {
+    log(`token usage extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Hook registration
 // ---------------------------------------------------------------------------
@@ -156,6 +232,9 @@ export function registerLifecycleHook(
         const shouldSubmit = result || !isExecFileMode;
         const taskResult = result ?? fallbackResult;
 
+        // Enrich with token usage from OpenClaw meta (if available)
+        enrichWithTokenUsage(taskResult, endCtx, taskMode);
+
         // Retry with backoff — task results are critical, losing them means
         // the task stays "running" forever and the workflow chain stalls.
         let posted = false;

package/src/index.ts

@@ -87,10 +87,10 @@ async function autoDetectModels(apiKey: string): Promise<void> {
     const currentCreative = data.aiModels?.creative;
 
     // Only auto-switch if still on Anthropic defaults (respect manual choices)
-    if (
+    const isAnthropicDefault =
       currentFast === "anthropic/claude-haiku-4-5" &&
-      currentCreative === "anthropic/claude-sonnet-4-6"
-    ) {
+      (currentCreative === "anthropic/claude-haiku-4-5" || currentCreative === "anthropic/claude-sonnet-4-6");
+    if (isAnthropicDefault) {
       const patchRes = await fetch(`${API_BASE}/me/settings`, {
         method: "PATCH",
         headers: {
@@ -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) {