@coffeexdev/openclaw-sentinel 0.5.1 → 0.7.0

package/dist/strategies/sse.js

@@ -1,41 +1,73 @@
+function isAbortError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.name === "AbortError" || err.message.toLowerCase().includes("aborted");
+}
 export const sseStrategy = async (watcher, onPayload, onError) => {
     let active = true;
+    let inFlightAbort;
+    let sleepTimer;
+    const wait = (ms) => new Promise((resolve) => {
+        sleepTimer = setTimeout(() => {
+            sleepTimer = undefined;
+            resolve();
+        }, ms);
+    });
     const loop = async () => {
         while (active) {
             try {
+                inFlightAbort = new AbortController();
                 const response = await fetch(watcher.endpoint, {
                     headers: { Accept: "text/event-stream", ...(watcher.headers ?? {}) },
-                    signal: AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                    signal: AbortSignal.any([
+                        inFlightAbort.signal,
+                        AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                    ]),
+                    redirect: "error",
                 });
                 if (!response.ok)
                     throw new Error(`sse non-2xx: ${response.status}`);
                 const contentType = response.headers.get("content-type") ?? "";
-                if (!contentType.toLowerCase().includes("text/event-stream"))
+                if (!contentType.toLowerCase().includes("text/event-stream")) {
                     throw new Error(`sse expected text/event-stream, got: ${contentType || "unknown"}`);
+                }
                 const text = await response.text();
                 for (const line of text.split("\n")) {
-                    if (line.startsWith("data:")) {
-                        const raw = line.slice(5).trim();
-                        if (!raw)
-                            continue;
-                        try {
-                            await onPayload(JSON.parse(raw));
-                        }
-                        catch {
-                            await onPayload({ message: raw });
-                        }
+                    if (!line.startsWith("data:"))
+                        continue;
+                    const raw = line.slice(5).trim();
+                    if (!raw)
+                        continue;
+                    try {
+                        await onPayload(JSON.parse(raw));
+                    }
+                    catch {
+                        await onPayload({ message: raw });
                     }
                 }
-                await new Promise((r) => setTimeout(r, watcher.intervalMs ?? 1000));
+                if (active) {
+                    await wait(watcher.intervalMs ?? 1000);
+                }
             }
             catch (err) {
+                if (!active && isAbortError(err))
+                    return;
                 await onError(err);
                 return;
             }
+            finally {
+                inFlightAbort = undefined;
+            }
         }
     };
     void loop();
     return async () => {
         active = false;
+        inFlightAbort?.abort();
+        inFlightAbort = undefined;
+        if (sleepTimer) {
+            clearTimeout(sleepTimer);
+            sleepTimer = undefined;
+        }
     };
 };

package/dist/strategies/websocket.js

@@ -1,14 +1,42 @@
 import WebSocket from "ws";
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
 export const websocketStrategy = async (watcher, onPayload, onError, callbacks) => {
     let active = true;
     let ws = null;
+    let connectTimer;
+    const clearConnectTimer = () => {
+        if (!connectTimer)
+            return;
+        clearTimeout(connectTimer);
+        connectTimer = undefined;
+    };
+    const connectTimeoutMs = Math.max(1, watcher.timeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS);
     const connect = () => {
         let pendingError = null;
         let failureReported = false;
-        ws = new WebSocket(watcher.endpoint, { headers: watcher.headers });
+        const reportFailure = (reason) => {
+            if (!active || failureReported)
+                return;
+            failureReported = true;
+            clearConnectTimer();
+            void onError(reason);
+        };
+        ws = new WebSocket(watcher.endpoint, {
+            headers: watcher.headers,
+            handshakeTimeout: connectTimeoutMs,
+        });
+        connectTimer = setTimeout(() => {
+            if (!active || !ws)
+                return;
+            if (ws.readyState === WebSocket.CONNECTING) {
+                pendingError = new Error(`websocket connect timeout after ${connectTimeoutMs}ms`);
+                ws.terminate();
+            }
+        }, connectTimeoutMs);
         ws.on("open", () => {
             if (!active)
                 return;
+            clearConnectTimer();
             callbacks?.onConnect?.();
         });
         ws.on("message", async (data) => {
@@ -28,17 +56,24 @@ export const websocketStrategy = async (watcher, onPayload, onError, callbacks)
             pendingError = err instanceof Error ? err : new Error(String(err));
         });
         ws.on("close", (code) => {
-            if (!active || failureReported)
+            if (!active)
                 return;
-            failureReported = true;
             const reason = pendingError?.message ?? `websocket closed: ${code}`;
-            void onError(new Error(reason));
+            reportFailure(new Error(reason));
         });
     };
     connect();
     return async () => {
         active = false;
-        if (ws && ws.readyState === WebSocket.OPEN)
+        clearConnectTimer();
+        if (!ws)
+            return;
+        if (ws.readyState === WebSocket.CONNECTING) {
+            ws.terminate();
+            return;
+        }
+        if (ws.readyState === WebSocket.OPEN) {
             ws.close();
+        }
     };
 };

package/dist/template.js

@@ -1,7 +1,5 @@
+import { getPath } from "./utils.js";
 const placeholderPattern = /^\$\{(watcher\.(id|skillId)|event\.(name)|payload\.[a-zA-Z0-9_.-]+|timestamp)\}$/;
-function getPath(obj, path) {
-    return path.split(".").reduce((acc, part) => acc?.[part], obj);
-}
 function renderValue(value, context) {
     if (value === null || typeof value === "number" || typeof value === "boolean")
         return value;

package/dist/toolSchema.js

@@ -1,6 +1,7 @@
 import { Type } from "@sinclair/typebox";
 import { TemplateValueSchema } from "./templateValueSchema.js";
 const TemplateValueRefSchema = Type.Ref(TemplateValueSchema);
+const WATCHER_ID_PATTERN = "^[A-Za-z0-9_-]{1,128}$";
 const ConditionSchema = Type.Object({
     path: Type.String({ description: "JSONPath expression to evaluate against the response" }),
     op: Type.Union([
@@ -58,7 +59,11 @@ const DeliveryTargetSchema = Type.Object({
     accountId: Type.Optional(Type.String({ description: "Optional account id for multi-account channels" })),
 }, { additionalProperties: false });
 const WatcherSchema = Type.Object({
-    id: Type.String({ description: "Unique watcher identifier" }),
+    id: Type.String({
+        pattern: WATCHER_ID_PATTERN,
+        maxLength: 128,
+        description: "Unique watcher identifier (letters, numbers, hyphen, underscore)",
+    }),
     skillId: Type.String({ description: "ID of the skill that owns this watcher" }),
     enabled: Type.Boolean({ description: "Whether the watcher is actively polling" }),
     strategy: Type.Union([
@@ -114,7 +119,11 @@ const CreateActionSchema = Type.Object({
 }, { additionalProperties: false });
 const IdActionSchema = Type.Object({
     action: IdActionNameSchema,
-    id: Type.String({ description: "Watcher ID for action target" }),
+    id: Type.String({
+        pattern: WATCHER_ID_PATTERN,
+        maxLength: 128,
+        description: "Watcher ID for action target",
+    }),
 }, { additionalProperties: false });
 const ListActionSchema = Type.Object({
     action: ListActionNameSchema,
@@ -127,7 +136,11 @@ export const SentinelToolValidationSchema = Type.Union([CreateActionSchema, IdAc
 export const SentinelToolSchema = Type.Object({
     action: AnyActionNameSchema,
     watcher: Type.Optional(WatcherSchema),
-    id: Type.Optional(Type.String({ description: "Watcher ID for action target" })),
+    id: Type.Optional(Type.String({
+        pattern: WATCHER_ID_PATTERN,
+        maxLength: 128,
+        description: "Watcher ID for action target",
+    })),
 }, {
     additionalProperties: false,
     $defs: {

package/dist/types.d.ts

@@ -67,6 +67,8 @@ export interface WatcherRuntimeState {
     lastConnectAt?: string;
     lastDisconnectAt?: string;
     lastDisconnectReason?: string;
+    lastDispatchError?: string;
+    lastDispatchErrorAt?: string;
     lastDelivery?: {
         attemptedAt: string;
         successCount: number;

package/dist/utils.d.ts

@@ -0,0 +1 @@
+export declare function getPath(obj: unknown, path: string): unknown;

package/dist/utils.js

@@ -0,0 +1,9 @@
+export function getPath(obj, path) {
+    if (!path)
+        return obj;
+    return path.split(".").reduce((acc, part) => {
+        if (acc === null || acc === undefined)
+            return undefined;
+        return acc[part];
+    }, obj);
+}

package/dist/validator.js

@@ -5,6 +5,7 @@ import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
 const TemplateValueRefSchema = Type.Ref(TemplateValueSchema);
 const codeyKeyPattern = /(script|code|eval|handler|function|import|require)/i;
 const codeyValuePattern = /(=>|\bfunction\b|\bimport\s+|\brequire\s*\(|\beval\s*\()/i;
+const WATCHER_ID_PATTERN = "^[A-Za-z0-9_-]{1,128}$";
 const ConditionSchema = Type.Object({
     path: Type.String({ minLength: 1 }),
     op: Type.Union([
@@ -23,7 +24,7 @@ const ConditionSchema = Type.Object({
     value: Type.Optional(Type.Unknown()),
 }, { additionalProperties: false });
 export const WatcherSchema = Type.Object({
-    id: Type.String({ minLength: 1 }),
+    id: Type.String({ pattern: WATCHER_ID_PATTERN, maxLength: 128 }),
     skillId: Type.String({ minLength: 1 }),
     enabled: Type.Boolean(),
     strategy: Type.Union([

package/dist/watcherManager.d.ts

@@ -6,6 +6,11 @@ export interface WatcherCreateContext {
 export interface WatcherNotifier {
     notify(target: DeliveryTarget, message: string): Promise<void>;
 }
+export interface WatcherLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+    error?(message: string): void;
+}
 export declare const backoff: (base: number, max: number, failures: number) => number;
 export declare class WatcherManager {
     private config;
@@ -16,6 +21,7 @@ export declare class WatcherManager {
     private stops;
     private retryTimers;
     private statePath;
+    private logger?;
     private webhookRegistration;
     constructor(config: SentinelConfig, dispatcher: GatewayWebhookDispatcher, notifier?: WatcherNotifier | undefined);
     init(): Promise<void>;
@@ -23,6 +29,7 @@ export declare class WatcherManager {
     list(): WatcherDefinition[];
     status(id: string): WatcherRuntimeState | undefined;
     setNotifier(notifier: WatcherNotifier | undefined): void;
+    setLogger(logger: WatcherLogger | undefined): void;
     setWebhookRegistrationStatus(status: "ok" | "error", message?: string, path?: string): void;
     enable(id: string): Promise<void>;
     disable(id: string): Promise<void>;

package/dist/watcherManager.js

@@ -50,6 +50,7 @@ export class WatcherManager {
     stops = new Map();
     retryTimers = new Map();
     statePath;
+    logger;
     webhookRegistration = {
         path: DEFAULT_SENTINEL_WEBHOOK_PATH,
         status: "pending",
@@ -81,6 +82,8 @@ export class WatcherManager {
                     lastEvaluated: prev?.lastEvaluated,
                     lastPayloadHash: prev?.lastPayloadHash,
                     lastPayload: prev?.lastPayload,
+                    lastDispatchError: prev?.lastDispatchError,
+                    lastDispatchErrorAt: prev?.lastDispatchErrorAt,
                 };
             }
         }
@@ -112,6 +115,9 @@ export class WatcherManager {
     setNotifier(notifier) {
         this.notifier = notifier;
     }
+    setLogger(logger) {
+        this.logger = logger;
+    }
     setWebhookRegistrationStatus(status, message, path) {
         this.webhookRegistration = {
             path: path ?? this.webhookRegistration.path,
@@ -213,39 +219,58 @@ export class WatcherManager {
                     matchedAt,
                     webhookPath,
                 });
-                await this.dispatcher.dispatch(webhookPath, body);
-                const deliveryMode = resolveNotificationPayloadMode(this.config, watcher);
-                const isSentinelWebhook = webhookPath === DEFAULT_SENTINEL_WEBHOOK_PATH;
-                if (deliveryMode !== "none" &&
-                    watcher.deliveryTargets?.length &&
-                    this.notifier &&
-                    !isSentinelWebhook) {
-                    const attemptedAt = new Date().toISOString();
-                    const message = buildDeliveryNotificationMessage(watcher, body, deliveryMode);
-                    const failures = [];
-                    let successCount = 0;
-                    await Promise.all(watcher.deliveryTargets.map(async (target) => {
-                        try {
-                            await this.notifier?.notify(target, message);
-                            successCount += 1;
-                        }
-                        catch (err) {
-                            failures.push({
-                                target,
-                                error: String(err?.message ?? err),
-                            });
-                        }
-                    }));
-                    rt.lastDelivery = {
-                        attemptedAt,
-                        successCount,
-                        failureCount: failures.length,
-                        failures: failures.length > 0 ? failures : undefined,
-                    };
+                let dispatchSucceeded = false;
+                try {
+                    await this.dispatcher.dispatch(webhookPath, body);
+                    dispatchSucceeded = true;
+                    rt.lastDispatchError = undefined;
+                    rt.lastDispatchErrorAt = undefined;
+                }
+                catch (err) {
+                    const message = String(err?.message ?? err);
+                    const status = err?.status;
+                    rt.lastDispatchError = message;
+                    rt.lastDispatchErrorAt = new Date().toISOString();
+                    rt.lastError = message;
+                    this.logger?.warn?.(`[openclaw-sentinel] Dispatch failed for watcher=${watcher.id} webhookPath=${webhookPath}: ${message}`);
+                    if (status === 401 || status === 403) {
+                        this.logger?.warn?.("[openclaw-sentinel] Dispatch authorization rejected (401/403). dispatchAuthToken may be missing or invalid. Sentinel now auto-detects gateway auth token when possible; explicit config/env overrides still take precedence.");
+                    }
                 }
-                if (watcher.fireOnce) {
-                    watcher.enabled = false;
-                    await this.stopWatcher(id);
+                if (dispatchSucceeded) {
+                    const deliveryMode = resolveNotificationPayloadMode(this.config, watcher);
+                    const isSentinelWebhook = webhookPath === DEFAULT_SENTINEL_WEBHOOK_PATH;
+                    if (deliveryMode !== "none" &&
+                        watcher.deliveryTargets?.length &&
+                        this.notifier &&
+                        !isSentinelWebhook) {
+                        const attemptedAt = new Date().toISOString();
+                        const message = buildDeliveryNotificationMessage(watcher, body, deliveryMode);
+                        const failures = [];
+                        let successCount = 0;
+                        await Promise.all(watcher.deliveryTargets.map(async (target) => {
+                            try {
+                                await this.notifier?.notify(target, message);
+                                successCount += 1;
+                            }
+                            catch (err) {
+                                failures.push({
+                                    target,
+                                    error: String(err?.message ?? err),
+                                });
+                            }
+                        }));
+                        rt.lastDelivery = {
+                            attemptedAt,
+                            successCount,
+                            failureCount: failures.length,
+                            failures: failures.length > 0 ? failures : undefined,
+                        };
+                    }
+                    if (watcher.fireOnce) {
+                        watcher.enabled = false;
+                        await this.stopWatcher(id);
+                    }
                 }
             }
             await this.persist();

package/openclaw.plugin.json

@@ -19,7 +19,7 @@
       },
       "dispatchAuthToken": {
         "type": "string",
-        "description": "Bearer token for authenticating webhook dispatch requests"
+        "description": "Optional bearer token override for webhook dispatch auth. Sentinel auto-detects gateway auth token when available."
       },
       "hookSessionKey": {
         "type": "string",
@@ -35,7 +35,7 @@
         "description": "Optional default session group key. When set, callbacks without explicit hookSessionGroup are routed to this group session."
       },
       "hookRelayDedupeWindowMs": {
-        "type": "number",
+        "type": "integer",
         "minimum": 0,
         "description": "Suppress duplicate relay messages for the same dedupe key within this window (milliseconds)",
         "default": 120000
@@ -56,29 +56,29 @@
         "description": "Resource limits for watcher creation",
         "properties": {
           "maxWatchersTotal": {
-            "type": "number",
+            "type": "integer",
             "description": "Maximum total watchers across all skills",
             "default": 200
           },
           "maxWatchersPerSkill": {
-            "type": "number",
+            "type": "integer",
             "description": "Maximum watchers per skill",
             "default": 20
           },
           "maxConditionsPerWatcher": {
-            "type": "number",
+            "type": "integer",
             "description": "Maximum conditions per watcher definition",
             "default": 25
           },
           "maxIntervalMsFloor": {
-            "type": "number",
+            "type": "integer",
             "description": "Minimum allowed polling interval in milliseconds",
             "default": 1000
           }
         }
       },
       "hookResponseTimeoutMs": {
-        "type": "number",
+        "type": "integer",
         "minimum": 0,
         "description": "Milliseconds to wait for an assistant-authored hook response before optional fallback relay",
         "default": 30000
@@ -90,7 +90,7 @@
         "default": "concise"
       },
       "hookResponseDedupeWindowMs": {
-        "type": "number",
+        "type": "integer",
         "minimum": 0,
         "description": "Deduplicate hook response-delivery contracts by dedupe key within this window (milliseconds)",
         "default": 120000
@@ -108,7 +108,7 @@
     },
     "dispatchAuthToken": {
       "label": "Dispatch Auth Token",
-      "help": "Bearer token for webhook dispatch authentication",
+      "help": "Optional override for webhook dispatch authentication. Sentinel auto-detects gateway auth token when available.",
       "sensitive": true,
       "placeholder": "sk-..."
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeexdev/openclaw-sentinel",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",