bereach-openclaw 1.5.8 → 1.5.10

package/node_modules/@bereach/tools/package.json

@@ -11,7 +11,10 @@
     "./utils": "./src/utils.ts",
     "./cache-types": "./src/cache-types.ts",
     "./parse-utils": "./src/parse-utils.ts",
-    "./task-tool-whitelist": "./src/task-tool-whitelist.ts"
+    "./task-tool-whitelist": "./src/task-tool-whitelist.ts",
+    "./api-client": "./src/api-client.ts",
+    "./cost-estimation": "./src/cost-estimation.ts",
+    "./llm-errors": "./src/llm-errors.ts"
   },
   "files": ["src/"],
   "scripts": {

package/node_modules/@bereach/tools/src/api-client.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared HTTP client for BeReach API calls.
+ * Handles retries, rate limiting, auth errors, and parameter interpolation.
+ *
+ * Used by both OpenClaw plugin and MCP server.
+ * The caller provides apiBase and apiKey — no build-time placeholders needed.
+ */
+
+import type { ToolDefinition } from "./types";
+
+const MAX_RETRIES = 2;
+const TIMEOUT_MS = 8000;
+
+// ---------------------------------------------------------------------------
+// URL building
+// ---------------------------------------------------------------------------
+
+/**
+ * Interpolate `{param}` placeholders in apiPath, returning the resolved path
+ * and the remaining body params (path params removed).
+ */
+function buildPath(
+  apiPath: string,
+  params: Record<string, unknown>,
+): { path: string; bodyParams: Record<string, unknown> } {
+  const bodyParams = { ...params };
+  const path = apiPath.replace(/\{(\w+)\}/g, (_, name) => {
+    const val = bodyParams[name];
+    if (val === undefined || val === null || val === "") {
+      throw new Error(`Missing required parameter: ${name} for ${apiPath}`);
+    }
+    delete bodyParams[name];
+    return encodeURIComponent(String(val));
+  });
+  return { path, bodyParams };
+}
+
+function buildUrl(
+  apiBase: string,
+  path: string,
+  method: string,
+  bodyParams: Record<string, unknown>,
+): string {
+  let url = `${apiBase}${path}`;
+  if (method === "GET" || method === "DELETE") {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(bodyParams)) {
+      if (v !== undefined && v !== null) qs.set(k, String(v));
+    }
+    const qsStr = qs.toString();
+    if (qsStr) url += `?${qsStr}`;
+  }
+  return url;
+}
+
+// ---------------------------------------------------------------------------
+// Response handling
+// ---------------------------------------------------------------------------
+
+function isReadOnly(method: string): boolean {
+  return method === "GET" || method === "DELETE";
+}
+
+/** Handle non-OK responses. Returns a wait-ms for 429, or throws (after reading body). */
+async function handleErrorResponse(resp: Response, path: string, method: string, attempt: number): Promise<number> {
+  if (resp.status === 429) {
+    const retryAfter = resp.headers.get("retry-after");
+    const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
+    return Number.isFinite(parsed) && parsed > 0
+      ? parsed * 1000
+      : backoffMs(attempt);
+  }
+  const errorBody = await resp.text().catch(() => "");
+  if (resp.status === 401) {
+    throw new Error(
+      "BeReach API key is invalid or expired (401 Unauthorized). " +
+      "The user should get a valid key at https://bereach.ai/token and set it with: /bereach-set-key brc_NEW_KEY",
+    );
+  }
+  throw new Error(`API ${method} ${path} failed (${resp.status}): ${errorBody}`);
+}
+
+// ---------------------------------------------------------------------------
+// Retry logic
+// ---------------------------------------------------------------------------
+
+function isTimeout(err: Error): boolean {
+  const m = err.message;
+  return m.includes("timed out") || m.includes("timeout") || m.includes("abort");
+}
+
+function isRetryable(err: Error): boolean {
+  const m = err.message;
+  // Non-retryable: explicit API failures and rate-limit errors we already handled
+  return !m.includes("failed (") && !m.includes("Rate limited");
+}
+
+function backoffMs(attempt: number): number {
+  return Math.pow(2, attempt + 1) * 1000;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute an API call for a tool definition.
+ * Interpolates path parameters, handles GET/POST, retries on transient failures.
+ */
+export async function executeApiCall(
+  def: ToolDefinition,
+  params: Record<string, unknown>,
+  apiKey: string,
+  apiBase: string,
+): Promise<unknown> {
+  const method = def.apiMethod ?? "POST";
+  const { path, bodyParams } = buildPath(def.apiPath!, params);
+  const url = buildUrl(apiBase, path, method, bodyParams);
+
+  let lastError: Error | null = null;
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const resp = await fetch(url, {
+        method,
+        headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+        ...(!isReadOnly(method) ? { body: JSON.stringify(bodyParams) } : {}),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+
+      if (!resp.ok) {
+        const waitMs = await handleErrorResponse(resp, path, method, attempt);
+        // 429: retry if attempts remain, otherwise throw
+        if (attempt < MAX_RETRIES) {
+          await new Promise((r) => setTimeout(r, waitMs));
+          continue;
+        }
+        const body = await resp.text().catch(() => "");
+        throw new Error(`Rate limited on ${path}. ${body}`);
+      }
+
+      return resp.json();
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+
+      // Don't retry write ops on timeout — the action may have succeeded server-side
+      if (!isReadOnly(method) && isTimeout(lastError)) throw lastError;
+
+      if (attempt < MAX_RETRIES && isRetryable(lastError)) {
+        await new Promise((r) => setTimeout(r, backoffMs(attempt)));
+        continue;
+      }
+      throw lastError;
+    }
+  }
+
+  throw lastError ?? new Error(`Failed after ${MAX_RETRIES + 1} attempts`);
+}

package/node_modules/@bereach/tools/src/cost-estimation.ts

@@ -0,0 +1,69 @@
+/**
+ * LLM cost estimation — model pricing and token usage extraction.
+ * Single source of truth, used by both lifecycle hook and connector.
+ */
+
+/** Model pricing per 1M tokens */
+export 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 },
+};
+
+export type TokenUsage = {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+};
+
+/**
+ * Estimate cost in USD from token usage.
+ * Matches model by substring (e.g. "claude-3-5-haiku" matches "haiku").
+ */
+export function estimateTaskCost(
+  inputTokens: number,
+  outputTokens: number,
+  cacheReadTokens: number,
+  modelSlug?: string | null,
+): 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;
+}
+
+/**
+ * Extract token usage from an OpenClaw meta/wrapper object.
+ * Handles multiple data locations across OpenClaw versions:
+ *   - meta.agentMeta.lastCallUsage (OpenClaw 2026.4+)
+ *   - meta.cost (older versions / test runner)
+ *   - meta.usage (alternative format)
+ */
+export function extractTokenUsage(
+  meta: Record<string, unknown>,
+): { usage: TokenUsage; model?: string } | null {
+  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,
+  };
+}

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

@@ -2055,18 +2055,6 @@ export const definitions: ToolDefinition[] = [
     },
   },
 
-  // ── Self Upgrade ────────────────────────────────────────────────
-
-  {
-    name: "bereach_self_upgrade",
-    description: "Upgrade the BeReach plugin to the latest version. Runs npm install and requires a session restart afterward.",
-    handler: "__self_upgrade__",
-    parameters: {
-      type: "object",
-      properties: {},
-    },
-  },
-
   // ── API Key Setup ────────────────────────────────────────────────
 
   {

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

@@ -123,7 +123,6 @@ export const FREE_TOOLS = new Set([
   "bereach_scheduled_message_cancel",
   "bereach_draft_schedule",
   "bereach_switch_account",
-  "bereach_self_upgrade",
   "bereach_get_dm_history",
   "bereach_get_conversation_summary",
   "bereach_save_conversation_summary",
@@ -171,7 +170,7 @@ export const PACING = {
 export const DEFAULTS = {
   maxVisitsPerSession: 200,
   engagementThreshold: 5,
-  contextCacheTtlMs: 5 * 60 * 1000, // 5 minutes
+  contextCacheTtlMs: 15 * 60 * 1000, // 15 minutes
   maxResultItems: 15,
   maxPostTextLength: 500,
 } as const;
@@ -275,31 +274,6 @@ export function createSessionState(): SessionState {
   };
 }
 
-// ---------------------------------------------------------------------------
-// Upgrade classification
-// ---------------------------------------------------------------------------
-
-export type UpgradeKind = "none" | "patch" | "minor" | "major";
-
-/** Compare two semver strings and return the upgrade kind. Strips prerelease tags. */
-export function classifyUpgrade(current: string, latest: string): UpgradeKind {
-  const parse = (v: string) => {
-    const cleaned = v.replace(/^v/i, "");
-    const [main, pre] = cleaned.split("-", 2);
-    const [major, minor, patch] = (main ?? "0.0.0").split(".").map(Number);
-    return { major: major || 0, minor: minor || 0, patch: patch || 0, pre: pre ?? "" };
-  };
-  const c = parse(current);
-  const l = parse(latest);
-  if (l.major !== c.major) return l.major > c.major ? "major" : "none";
-  if (l.minor !== c.minor) return l.minor > c.minor ? "minor" : "none";
-  if (l.patch !== c.patch) return l.patch > c.patch ? "patch" : "none";
-  // Same base version — prerelease-to-prerelease or prerelease-to-stable
-  if (c.pre && !l.pre) return "patch"; // beta → stable release of same version
-  if (c.pre && l.pre && l.pre !== c.pre) return "patch"; // beta.12 → beta.15
-  return "none";
-}
-
 // ---------------------------------------------------------------------------
 // Campaign types — DB is the single source of truth
 // ---------------------------------------------------------------------------

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

@@ -7,9 +7,9 @@ export {
   READ_TOOLS, WRITE_TOOLS, FREE_TOOLS, PACED_FREE_TOOLS,
   VISIT_FIRST_TOOLS, PROFILE_TARGETING_TOOLS,
   PACING, DEFAULTS,
-  createSessionState, classifyUpgrade,
+  createSessionState,
   type PluginConfig, type SessionState, type TaskModeInfo,
-  type DbCampaign, type UpgradeKind,
+  type DbCampaign,
 } from "./enforcement-types.js";
 
 // Pure enforcement rules
@@ -23,6 +23,7 @@ export {
 
 // Utilities (URL normalization, profile extraction, result parsing)
 export {
+  errMsg,
   createLogger, normalizeUrl, extractProfile, extractDmIdentifier,
   extractToolResult, isErrorResult,
 } from "./utils.js";
@@ -33,13 +34,24 @@ export type {
   CachedAccount, SessionMeta, OnboardingState, RecentEvent, CacheStore,
 } from "./cache-types.js";
 
-// Parse utilities (semver, structured result parsing)
+// Parse utilities (structured result parsing)
 export {
   extractTextFromContent, parseStructuredResult,
-  parseSemver, semverGt,
 } from "./parse-utils.js";
 
 // Task tool whitelists (per-task-type tool pruning)
 export {
   getTaskToolWhitelist, getTaskToolNames,
 } from "./task-tool-whitelist.js";
+
+// API client (HTTP call execution with retry, rate limiting)
+export { executeApiCall } from "./api-client.js";
+
+// Cost estimation (model pricing, token usage extraction)
+export {
+  MODEL_PRICING, estimateTaskCost, extractTokenUsage,
+  type TokenUsage,
+} from "./cost-estimation.js";
+
+// LLM error detection
+export { detectLlmError } from "./llm-errors.js";

package/node_modules/@bereach/tools/src/llm-errors.ts

@@ -0,0 +1,24 @@
+/**
+ * LLM provider error detection patterns.
+ * Mirrors apps/web/src/lib/errors/llm-errors.ts but self-contained
+ * (shared package has zero dependencies on apps/).
+ *
+ * Used by connector to detect auth/billing failures from agent output.
+ */
+
+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. */
+export 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;
+}

package/node_modules/@bereach/tools/src/parse-utils.ts

@@ -21,11 +21,16 @@ export function extractTextFromContent(content: unknown): string {
     const obj = content as Record<string, unknown>;
     if (typeof obj.text === "string") return obj.text;
     if (typeof obj.value === "string") return obj.value;
+    // Last resort: stringify
     return JSON.stringify(content);
   }
   return "";
 }
 
+// ---------------------------------------------------------------------------
+// Task result parser
+// ---------------------------------------------------------------------------
+
 /** Extract the last JSON block from agent output text. */
 export function parseStructuredResult(text: string): Record<string, unknown> | null {
   // Try fenced code blocks first
@@ -47,50 +52,4 @@ export function parseStructuredResult(text: string): Record<string, unknown> | n
   }
 
   return null;
-}
-
-// ---------------------------------------------------------------------------
-// Semver helpers (from context.ts)
-// ---------------------------------------------------------------------------
-
-interface SemverParts {
-  major: number;
-  minor: number;
-  patch: number;
-  pre: string;
-}
-
-export function parseSemver(v: string): SemverParts {
-  const cleaned = v.replace(/^v/i, "");
-  const [main, pre] = cleaned.split("-", 2);
-  const [major, minor, patch] = (main ?? "0.0.0").split(".").map(Number);
-  return { major: major || 0, minor: minor || 0, patch: patch || 0, pre: pre ?? "" };
-}
-
-/**
- * Lightweight semver "greater than" check. Returns true if a > b.
- * Handles prerelease tags (1.4.0 > 1.4.0-beta.1, 1.4.0-beta.5 > 1.4.0-beta.4).
- */
-export function semverGt(a: string, b: string): boolean {
-  const va = parseSemver(a);
-  const vb = parseSemver(b);
-
-  if (va.major !== vb.major) return va.major > vb.major;
-  if (va.minor !== vb.minor) return va.minor > vb.minor;
-  if (va.patch !== vb.patch) return va.patch > vb.patch;
-
-  // Release > prerelease
-  if (!va.pre && vb.pre) return true;
-  if (va.pre && !vb.pre) return false;
-
-  // Prerelease comparison: split into label + number (e.g. "beta.10" -> ["beta", 10])
-  const aParts = va.pre.split(".");
-  const bParts = vb.pre.split(".");
-  const aLabel = aParts.slice(0, -1).join(".");
-  const bLabel = bParts.slice(0, -1).join(".");
-  if (aLabel !== bLabel) return aLabel > bLabel;
-  const aNum = parseInt(aParts[aParts.length - 1] ?? "0", 10);
-  const bNum = parseInt(bParts[bParts.length - 1] ?? "0", 10);
-  if (!isNaN(aNum) && !isNaN(bNum) && aNum !== bNum) return aNum > bNum;
-  return va.pre > vb.pre;
-}
+}

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

@@ -6,6 +6,15 @@
  * (depend on build-time placeholder replacement).
  */
 
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+
+/** Extract message from an unknown catch value. */
+export function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // ---------------------------------------------------------------------------
 // Logger factory
 // ---------------------------------------------------------------------------

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "bereach-openclaw",
   "name": "BeReach",
-  "version": "1.5.8",
+  "version": "1.5.10",
   "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.8",
+  "version": "1.5.10",
   "description": "BeReach LinkedIn automation plugin for OpenClaw",
   "license": "AGPL-3.0",
   "exports": {
@@ -50,12 +50,12 @@
     "bereach": "1.5.0"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@upstash/box": "^0.1.30",
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^25.5.2",
+    "@upstash/box": "^0.1.32",
     "tsx": "^4.21.0",
     "typescript": "^6.0.2",
-    "@playwright/test": "^1.52.0",
-    "vitest": "^4.1.2",
+    "vitest": "^4.1.4",
     "zod": "^4.3.6"
   }
 }

package/skills/bereach/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: bereach
 description: "Automate LinkedIn outreach via BeReach (bereach.ai). Use when: prospecting, engaging posts, scraping engagement, searching LinkedIn, managing inbox, running campaigns, managing invitations, analytics, company pages, Sales Navigator, content engagement, feed monitoring. Requires BEREACH_API_KEY."
-lastUpdatedAt: 1775565279
+lastUpdatedAt: 1775759685
 metadata: { "openclaw": { "requires": { "env": ["BEREACH_API_KEY"] }, "primaryEnv": "BEREACH_API_KEY" } }
 ---
 
@@ -28,7 +28,7 @@ Load sub-skills **on-demand** when the user's request matches a workflow.
 | Warmup        | warmup, warm up, account warmup, engagement, likes, visibility, ramp up, pre-warming | sub/warmup.md | 1775410333 |
 | Content       | content, post, publish, LinkedIn post, content strategy, draft, article, thought leadership | sub/content.md | 1775410333 |
 | Inbox         | inbox, triage, classify, archive, star, respond, unread, conversation, spam, inbox management | sub/inbox.md | 1775410333 |
-| SDK Reference | sdk, method, parameter, script, TypeScript, generate code, automate | sdk-reference.md | 1775486606 |
+| SDK Reference | sdk, method, parameter, script, TypeScript, generate code, automate | sdk-reference.md | 1775759685 |
 
 ### Workspace Templates
 

package/skills/bereach/sdk-reference.md

@@ -1,7 +1,7 @@
 ---
 name: bereach-sdk-reference
 description: "Complete SDK method reference — parameters, types, and descriptions for all BeReach operations."
-lastUpdatedAt: 1775486606
+lastUpdatedAt: 1775759685
 ---
 
 <!--
@@ -1374,12 +1374,3 @@ Save a conversation summary after reviewing DM history. Include: topics, relatio
 - **profile** (string, required) — LinkedIn profile URL.
 - **summary** (string, required) — Your conversation summary (max 10,000 chars). Be concise but comprehensive.
 
-## __self_upgrade__
-
-### undefined
-
-Upgrade the BeReach plugin to the latest version. Runs npm install and requires a session restart afterward.
-
-`client.__self_upgrade__(params)`
-
-No parameters.

package/src/commands/connector/api.ts

@@ -0,0 +1,113 @@
+/**
+ * HTTP helpers for communicating with the BeReach API and gateway.
+ */
+
+import { type ConnectorConfig, type PullResponse, AuthError, MIN_POLL_MS } from "./types";
+import { errMsg } from "@bereach/tools/utils";
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const delay = Math.max(MIN_POLL_MS, ms);
+    const timer = setTimeout(resolve, delay);
+    signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+  });
+}
+
+export function buildHeaders(config: ConnectorConfig): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
+  }
+  return headers;
+}
+
+export async function httpPost(url: string, body: unknown, headers: Record<string, string>): Promise<unknown> {
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+  });
+  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();
+}
+
+export async function pullTask(config: ConnectorConfig): Promise<PullResponse> {
+  const headers = buildHeaders(config);
+  const body: Record<string, unknown> = {};
+  if (!config.apiKey && config.connectorToken) {
+    body.connectorToken = config.connectorToken;
+  }
+  return httpPost(`${config.apiUrl}/tasks/pull`, body, headers) as Promise<PullResponse>;
+}
+
+export async function submitResult(
+  config: ConnectorConfig,
+  taskId: string,
+  result: unknown,
+  error: string | null,
+): Promise<void> {
+  const headers = buildHeaders(config);
+  const body: Record<string, unknown> = { result, error };
+  if (!config.apiKey && config.connectorToken) {
+    body.connectorToken = config.connectorToken;
+  }
+  await httpPost(`${config.apiUrl}/tasks/${taskId}/result`, body, headers);
+}
+
+export async function heartbeat(
+  config: ConnectorConfig,
+  currentTaskId?: string,
+): Promise<{ pollIntervalMs: number }> {
+  const headers = buildHeaders(config);
+  const body: Record<string, unknown> = { currentTaskId };
+  if (!config.apiKey && config.connectorToken) {
+    body.connectorToken = config.connectorToken;
+  }
+  return httpPost(`${config.apiUrl}/connectors/heartbeat`, body, headers) as Promise<{ pollIntervalMs: number }>;
+}
+
+export async function updateTaskStatus(
+  config: ConnectorConfig,
+  taskId: string,
+  status: "accepted" | "running",
+): Promise<void> {
+  const headers = buildHeaders(config);
+  const body: Record<string, unknown> = { status };
+  if (!config.apiKey && config.connectorToken) {
+    body.connectorToken = config.connectorToken;
+  }
+  await httpPost(`${config.apiUrl}/tasks/${taskId}/result`, body, headers).catch((err) => {
+    console.error(`[connector] Task status update to "${status}" failed for ${taskId}: ${errMsg(err)}`);
+  });
+}
+
+/**
+ * Check if gateway webhook is available.
+ * Uses a HEAD request to avoid spawning an actual agent session.
+ * Falls back to checking if the gateway root responds at all.
+ */
+export async function isWebhookAvailable(config: ConnectorConfig): Promise<boolean> {
+  if (!config.gatewayUrl || !config.hooksToken) return false;
+  try {
+    const res = await fetch(`${config.gatewayUrl}/hooks/agent`, {
+      method: "OPTIONS",
+      headers: {
+        "Authorization": `Bearer ${config.hooksToken}`,
+      },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (res.status === 401 || res.status === 403) return false;
+    if (res.ok || res.status === 405 || res.status === 204) return true;
+
+    console.log(`[connector] Webhook probe: OPTIONS /hooks/agent returned ${res.status}, hooks not available`);
+    return false;
+  } catch {
+    return false;
+  }
+}