@coffeexdev/openclaw-sentinel 0.5.1 → 0.6.0

package/README.md

@@ -59,8 +59,9 @@ Add/update `~/.openclaw/openclaw.json`:
           // Optional legacy alias for hookSessionPrefix (still supported).
           // hookSessionKey: "agent:main:hooks:sentinel",
 
-          // Optional: bearer token used for dispatch calls back to gateway.
-          // Set this to your gateway auth token when gateway auth is enabled.
+          // Optional: explicit bearer token override for dispatch calls back to gateway.
+          // Sentinel auto-detects gateway auth token from runtime config when available,
+          // so manual token copy is usually no longer required.
           // dispatchAuthToken: "<gateway-token>"
         },
       },
@@ -89,6 +90,13 @@ your config is using the old root-level shape. Move Sentinel config under:
 
 Sentinel also logs a runtime warning when that legacy root key is still observable, but it never writes a root-level `sentinel` key.
 
+### Hardening notes (0.6 minor)
+
+- `hookSessionKey` remains supported but is deprecated. If both are present, `hookSessionPrefix` now wins.
+- HTTP watcher strategies now set `redirect: "error"` to prevent host-allowlist bypass via redirects.
+- Watcher IDs are now constrained to `^[A-Za-z0-9_-]{1,128}$`.
+- `/hooks/sentinel` validates JSON `Content-Type` when provided and returns `415` for unsupported media types.
+
 ### 4) Create your first watcher (`sentinel_control`)
 
 ```json
@@ -257,9 +265,16 @@ Global mode options:
 
 ```json5
 {
-  sentinel: {
-    allowedHosts: ["api.github.com"],
-    notificationPayloadMode: "none",
+  plugins: {
+    entries: {
+      "openclaw-sentinel": {
+        enabled: true,
+        config: {
+          allowedHosts: ["api.github.com"],
+          notificationPayloadMode: "none",
+        },
+      },
+    },
   },
 }
 ```
@@ -268,9 +283,16 @@ Global mode options:
 
 ```json5
 {
-  sentinel: {
-    allowedHosts: ["api.github.com"],
-    notificationPayloadMode: "concise",
+  plugins: {
+    entries: {
+      "openclaw-sentinel": {
+        enabled: true,
+        config: {
+          allowedHosts: ["api.github.com"],
+          notificationPayloadMode: "concise",
+        },
+      },
+    },
   },
 }
 ```
@@ -279,9 +301,16 @@ Global mode options:
 
 ```json5
 {
-  sentinel: {
-    allowedHosts: ["api.github.com"],
-    notificationPayloadMode: "debug",
+  plugins: {
+    entries: {
+      "openclaw-sentinel": {
+        enabled: true,
+        config: {
+          allowedHosts: ["api.github.com"],
+          notificationPayloadMode: "debug",
+        },
+      },
+    },
   },
 }
 ```

package/dist/callbackEnvelope.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { SENTINEL_ORIGIN_ACCOUNT_METADATA, SENTINEL_ORIGIN_CHANNEL_METADATA, SENTINEL_ORIGIN_SESSION_KEY_METADATA, SENTINEL_ORIGIN_TARGET_METADATA, } from "./types.js";
 import { renderTemplate } from "./template.js";
+import { getPath } from "./utils.js";
 const MAX_PAYLOAD_JSON_CHARS = 4000;
 function toIntent(eventName) {
     return (eventName
@@ -57,9 +58,6 @@ function buildDeliveryContextFromMetadata(watcher) {
     }
     return Object.keys(context).length > 0 ? context : undefined;
 }
-function getPath(obj, path) {
-    return path.split(".").reduce((acc, part) => acc?.[part], obj);
-}
 function getTemplateString(value, context) {
     if (!value)
         return undefined;

package/dist/configSchema.js

@@ -27,6 +27,42 @@ const ConfigSchema = Type.Object({
     notificationPayloadMode: Type.Optional(NotificationPayloadModeSchema),
     limits: Type.Optional(LimitsSchema),
 }, { additionalProperties: false });
+function trimToUndefined(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function findInvalidNumericPath(input) {
+    const numericPaths = [
+        "hookRelayDedupeWindowMs",
+        "hookResponseTimeoutMs",
+        "hookResponseDedupeWindowMs",
+    ];
+    for (const key of numericPaths) {
+        const value = input[key];
+        if (typeof value === "number" && !Number.isFinite(value)) {
+            return `/${key}`;
+        }
+    }
+    const limits = input.limits;
+    if (limits && typeof limits === "object" && !Array.isArray(limits)) {
+        const limitsRecord = limits;
+        const limitKeys = [
+            "maxWatchersTotal",
+            "maxWatchersPerSkill",
+            "maxConditionsPerWatcher",
+            "maxIntervalMsFloor",
+        ];
+        for (const key of limitKeys) {
+            const value = limitsRecord[key];
+            if (typeof value === "number" && !Number.isFinite(value)) {
+                return `/limits/${key}`;
+            }
+        }
+    }
+    return undefined;
+}
 function withDefaults(value) {
     const limitsIn = value.limits ?? {};
     return {
@@ -34,16 +70,23 @@ function withDefaults(value) {
         localDispatchBase: typeof value.localDispatchBase === "string" && value.localDispatchBase.length > 0
             ? value.localDispatchBase
             : "http://127.0.0.1:18789",
-        dispatchAuthToken: typeof value.dispatchAuthToken === "string" ? value.dispatchAuthToken : undefined,
+        dispatchAuthToken: trimToUndefined(value.dispatchAuthToken),
         hookSessionKey: typeof value.hookSessionKey === "string" ? value.hookSessionKey : undefined,
         hookSessionPrefix: typeof value.hookSessionPrefix === "string"
             ? value.hookSessionPrefix
             : "agent:main:hooks:sentinel",
         hookSessionGroup: typeof value.hookSessionGroup === "string" ? value.hookSessionGroup : undefined,
-        hookRelayDedupeWindowMs: typeof value.hookRelayDedupeWindowMs === "number" ? value.hookRelayDedupeWindowMs : 120000,
-        hookResponseTimeoutMs: typeof value.hookResponseTimeoutMs === "number" ? value.hookResponseTimeoutMs : 30000,
+        hookRelayDedupeWindowMs: typeof value.hookRelayDedupeWindowMs === "number" &&
+            Number.isFinite(value.hookRelayDedupeWindowMs)
+            ? value.hookRelayDedupeWindowMs
+            : 120000,
+        hookResponseTimeoutMs: typeof value.hookResponseTimeoutMs === "number" &&
+            Number.isFinite(value.hookResponseTimeoutMs)
+            ? value.hookResponseTimeoutMs
+            : 30000,
         hookResponseFallbackMode: value.hookResponseFallbackMode === "none" ? "none" : "concise",
-        hookResponseDedupeWindowMs: typeof value.hookResponseDedupeWindowMs === "number"
+        hookResponseDedupeWindowMs: typeof value.hookResponseDedupeWindowMs === "number" &&
+            Number.isFinite(value.hookResponseDedupeWindowMs)
             ? value.hookResponseDedupeWindowMs
             : 120000,
         stateFilePath: typeof value.stateFilePath === "string" ? value.stateFilePath : undefined,
@@ -53,12 +96,21 @@ function withDefaults(value) {
                 ? "debug"
                 : "concise",
         limits: {
-            maxWatchersTotal: typeof limitsIn.maxWatchersTotal === "number" ? limitsIn.maxWatchersTotal : 200,
-            maxWatchersPerSkill: typeof limitsIn.maxWatchersPerSkill === "number" ? limitsIn.maxWatchersPerSkill : 20,
-            maxConditionsPerWatcher: typeof limitsIn.maxConditionsPerWatcher === "number"
+            maxWatchersTotal: typeof limitsIn.maxWatchersTotal === "number" && Number.isFinite(limitsIn.maxWatchersTotal)
+                ? limitsIn.maxWatchersTotal
+                : 200,
+            maxWatchersPerSkill: typeof limitsIn.maxWatchersPerSkill === "number" &&
+                Number.isFinite(limitsIn.maxWatchersPerSkill)
+                ? limitsIn.maxWatchersPerSkill
+                : 20,
+            maxConditionsPerWatcher: typeof limitsIn.maxConditionsPerWatcher === "number" &&
+                Number.isFinite(limitsIn.maxConditionsPerWatcher)
                 ? limitsIn.maxConditionsPerWatcher
                 : 25,
-            maxIntervalMsFloor: typeof limitsIn.maxIntervalMsFloor === "number" ? limitsIn.maxIntervalMsFloor : 1000,
+            maxIntervalMsFloor: typeof limitsIn.maxIntervalMsFloor === "number" &&
+                Number.isFinite(limitsIn.maxIntervalMsFloor)
+                ? limitsIn.maxIntervalMsFloor
+                : 1000,
         },
     };
 }
@@ -79,7 +131,17 @@ export const sentinelConfigSchema = {
                 error: { issues: [issue("/", "Config must be an object")] },
             };
         }
-        const candidate = withDefaults(value);
+        const source = value;
+        const invalidNumericPath = findInvalidNumericPath(source);
+        if (invalidNumericPath) {
+            return {
+                success: false,
+                error: {
+                    issues: [issue(invalidNumericPath, "Expected a finite number")],
+                },
+            };
+        }
+        const candidate = withDefaults(source);
         if (!Value.Check(ConfigSchema, candidate)) {
             const first = [...Value.Errors(ConfigSchema, candidate)][0];
             return {
@@ -120,7 +182,7 @@ export const sentinelConfigSchema = {
             },
             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",
@@ -136,13 +198,13 @@ export const sentinelConfigSchema = {
                 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,
             },
             hookResponseTimeoutMs: {
-                type: "number",
+                type: "integer",
                 minimum: 0,
                 description: "Milliseconds to wait for an assistant-authored hook response before optional fallback relay",
                 default: 30000,
@@ -154,7 +216,7 @@ export const sentinelConfigSchema = {
                 default: "concise",
             },
             hookResponseDedupeWindowMs: {
-                type: "number",
+                type: "integer",
                 minimum: 0,
                 description: "Deduplicate hook response-delivery contracts by dedupe key within this window (milliseconds)",
                 default: 120000,
@@ -175,22 +237,22 @@ export const sentinelConfigSchema = {
                 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,
                     },
@@ -209,7 +271,7 @@ export const sentinelConfigSchema = {
         },
         dispatchAuthToken: {
             label: "Dispatch Auth Token",
-            help: "Bearer token for webhook dispatch authentication (or use SENTINEL_DISPATCH_TOKEN env var)",
+            help: "Optional override for webhook dispatch auth token. Sentinel auto-detects gateway auth token when available (or use SENTINEL_DISPATCH_TOKEN env var).",
             sensitive: true,
             placeholder: "sk-...",
         },

package/dist/evaluator.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import { createRequire } from "node:module";
+import { getPath } from "./utils.js";
 const require = createRequire(import.meta.url);
 let cachedRegexCtor = null;
 function getSafeRegexCtor() {
@@ -26,9 +27,6 @@ function getSafeRegexCtor() {
         throw new Error("No safe regex engine available (re2/re2-wasm)");
     }
 }
-function getPath(obj, path) {
-    return path.split(".").reduce((acc, part) => acc?.[part], obj);
-}
 function safeRegexTest(pattern, input) {
     if (pattern.length > 256)
         throw new Error("Regex pattern too long");

package/dist/index.js

@@ -8,6 +8,7 @@ const DEFAULT_HOOK_SESSION_PREFIX = "agent:main:hooks:sentinel";
 const DEFAULT_RELAY_DEDUPE_WINDOW_MS = 120_000;
 const DEFAULT_HOOK_RESPONSE_TIMEOUT_MS = 30_000;
 const DEFAULT_HOOK_RESPONSE_FALLBACK_MODE = "concise";
+const HOOK_RESPONSE_RELAY_CLEANUP_INTERVAL_MS = 60_000;
 const MAX_SENTINEL_WEBHOOK_BODY_BYTES = 64 * 1024;
 const MAX_SENTINEL_WEBHOOK_TEXT_CHARS = 8000;
 const MAX_SENTINEL_PAYLOAD_JSON_CHARS = 2500;
@@ -43,20 +44,48 @@ function asIsoString(value) {
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function sniffGatewayDispatchToken(configRoot) {
+    if (!configRoot)
+        return undefined;
+    const auth = isRecord(configRoot.auth) ? configRoot.auth : undefined;
+    const gateway = isRecord(configRoot.gateway) ? configRoot.gateway : undefined;
+    const gatewayAuth = gateway && isRecord(gateway.auth) ? gateway.auth : undefined;
+    const server = isRecord(configRoot.server) ? configRoot.server : undefined;
+    const serverAuth = server && isRecord(server.auth) ? server.auth : undefined;
+    const candidates = [
+        auth?.token,
+        gateway?.authToken,
+        gatewayAuth?.token,
+        serverAuth?.token,
+        configRoot.gatewayAuthToken,
+        configRoot.authToken,
+    ];
+    for (const candidate of candidates) {
+        const token = asString(candidate);
+        if (token)
+            return token;
+    }
+    return undefined;
+}
 function resolveSentinelPluginConfig(api) {
     const pluginConfig = isRecord(api.pluginConfig)
-        ? api.pluginConfig
+        ? { ...api.pluginConfig }
         : {};
     const configRoot = isRecord(api.config) ? api.config : undefined;
     const legacyRootConfig = configRoot?.sentinel;
-    if (legacyRootConfig === undefined)
-        return pluginConfig;
-    api.logger?.warn?.('[openclaw-sentinel] Detected deprecated root-level config key "sentinel". Move settings to plugins.entries.openclaw-sentinel.config. Root-level "sentinel" may fail with: Unrecognized key: "sentinel".');
-    if (!isRecord(legacyRootConfig))
-        return pluginConfig;
-    if (Object.keys(pluginConfig).length > 0)
-        return pluginConfig;
-    return legacyRootConfig;
+    let resolved = pluginConfig;
+    if (legacyRootConfig !== undefined) {
+        api.logger?.warn?.('[openclaw-sentinel] Detected deprecated root-level config key "sentinel". Move settings to plugins.entries.openclaw-sentinel.config. Root-level "sentinel" may fail with: Unrecognized key: "sentinel".');
+        if (isRecord(legacyRootConfig) && Object.keys(pluginConfig).length === 0) {
+            resolved = { ...legacyRootConfig };
+        }
+    }
+    if (!asString(resolved.dispatchAuthToken)) {
+        const sniffedToken = sniffGatewayDispatchToken(configRoot);
+        if (sniffedToken)
+            resolved.dispatchAuthToken = sniffedToken;
+    }
+    return resolved;
 }
 function isDeliveryTarget(value) {
     return (isRecord(value) &&
@@ -334,9 +363,12 @@ function resolveHookResponseFallbackMode(config) {
     return config.hookResponseFallbackMode === "none" ? "none" : DEFAULT_HOOK_RESPONSE_FALLBACK_MODE;
 }
 function buildIsolatedHookSessionKey(envelope, config) {
-    const rawPrefix = asString(config.hookSessionKey) ??
-        asString(config.hookSessionPrefix) ??
-        DEFAULT_HOOK_SESSION_PREFIX;
+    const configuredPrefix = asString(config.hookSessionPrefix);
+    const legacyPrefix = asString(config.hookSessionKey);
+    const hasCustomPrefix = typeof configuredPrefix === "string" && configuredPrefix !== DEFAULT_HOOK_SESSION_PREFIX;
+    const rawPrefix = hasCustomPrefix
+        ? configuredPrefix
+        : (legacyPrefix ?? configuredPrefix ?? DEFAULT_HOOK_SESSION_PREFIX);
     const prefix = rawPrefix.replace(/:+$/g, "");
     const group = asString(envelope.hookSessionGroup) ?? asString(config.hookSessionGroup);
     if (group) {
@@ -350,10 +382,28 @@ function buildIsolatedHookSessionKey(envelope, config) {
     }
     return `${prefix}:event:unknown`;
 }
+function assertJsonContentType(req) {
+    const raw = req.headers["content-type"];
+    const header = Array.isArray(raw) ? raw[0] : raw;
+    if (!header)
+        return;
+    const normalized = header.toLowerCase();
+    const isJson = normalized.includes("application/json") ||
+        normalized.includes("application/cloudevents+json") ||
+        normalized.includes("+json");
+    if (!isJson) {
+        throw new Error(`Unsupported Content-Type: ${header}`);
+    }
+}
 async function readSentinelWebhookPayload(req) {
+    assertJsonContentType(req);
     const preParsed = req.body;
-    if (isRecord(preParsed))
+    if (preParsed !== undefined) {
+        if (!isRecord(preParsed)) {
+            throw new Error("Payload must be a JSON object");
+        }
         return preParsed;
+    }
     const chunks = [];
     let total = 0;
     for await (const chunk of req) {
@@ -446,21 +496,16 @@ class HookResponseRelayManager {
     recentByDedupe = new Map();
     pendingByDedupe = new Map();
     pendingQueueBySession = new Map();
+    cleanupTimer;
+    disposed = false;
     constructor(config, api) {
         this.config = config;
         this.api = api;
     }
     register(args) {
+        this.cleanup();
         const dedupeWindowMs = resolveHookResponseDedupeWindowMs(this.config);
         const now = Date.now();
-        if (dedupeWindowMs > 0) {
-            for (const [key, ts] of this.recentByDedupe.entries()) {
-                if (now - ts > dedupeWindowMs) {
-                    this.recentByDedupe.delete(key);
-                    this.pendingByDedupe.delete(key);
-                }
-            }
-        }
         const existingTs = this.recentByDedupe.get(args.dedupeKey);
         if (dedupeWindowMs > 0 &&
             typeof existingTs === "number" &&
@@ -477,6 +522,7 @@ class HookResponseRelayManager {
             };
         }
         this.recentByDedupe.set(args.dedupeKey, now);
+        this.scheduleCleanup();
         const timeoutMs = resolveHookResponseTimeoutMs(this.config);
         const fallbackMode = resolveHookResponseFallbackMode(this.config);
         if (args.relayTargets.length === 0) {
@@ -538,6 +584,64 @@ class HookResponseRelayManager {
             return;
         await this.completeWithMessage(pending, assistantMessage, "assistant");
     }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.cleanupTimer) {
+            clearTimeout(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        for (const pending of this.pendingByDedupe.values()) {
+            if (pending.timer) {
+                clearTimeout(pending.timer);
+                pending.timer = undefined;
+            }
+        }
+        this.pendingByDedupe.clear();
+        this.pendingQueueBySession.clear();
+        this.recentByDedupe.clear();
+    }
+    scheduleCleanup() {
+        if (this.disposed || this.cleanupTimer)
+            return;
+        this.cleanupTimer = setTimeout(() => {
+            this.cleanupTimer = undefined;
+            this.cleanup();
+        }, HOOK_RESPONSE_RELAY_CLEANUP_INTERVAL_MS);
+        this.cleanupTimer.unref?.();
+    }
+    cleanup(now = Date.now()) {
+        const dedupeWindowMs = resolveHookResponseDedupeWindowMs(this.config);
+        if (dedupeWindowMs > 0) {
+            for (const [key, ts] of this.recentByDedupe.entries()) {
+                if (now - ts > dedupeWindowMs) {
+                    this.recentByDedupe.delete(key);
+                }
+            }
+        }
+        for (const [key, pending] of this.pendingByDedupe.entries()) {
+            const gcAfterMs = Math.max(pending.timeoutMs, dedupeWindowMs, 1_000);
+            if (pending.state !== "pending" && now - pending.createdAt > gcAfterMs) {
+                this.pendingByDedupe.delete(key);
+                this.removeFromSessionQueue(pending.sessionKey, key);
+            }
+        }
+        if (this.pendingByDedupe.size > 0 || this.recentByDedupe.size > 0) {
+            this.scheduleCleanup();
+        }
+    }
+    removeFromSessionQueue(sessionKey, dedupeKey) {
+        const queue = this.pendingQueueBySession.get(sessionKey);
+        if (!queue || queue.length === 0)
+            return;
+        const filtered = queue.filter((key) => key !== dedupeKey);
+        if (filtered.length === 0) {
+            this.pendingQueueBySession.delete(sessionKey);
+            return;
+        }
+        this.pendingQueueBySession.set(sessionKey, filtered);
+    }
     popNextPendingDedupe(sessionKey) {
         const queue = this.pendingQueueBySession.get(sessionKey);
         if (!queue || queue.length === 0)
@@ -586,7 +690,7 @@ export function createSentinelPlugin(overrides) {
     const config = {
         allowedHosts: [],
         localDispatchBase: "http://127.0.0.1:18789",
-        dispatchAuthToken: process.env.SENTINEL_DISPATCH_TOKEN,
+        dispatchAuthToken: asString(process.env.SENTINEL_DISPATCH_TOKEN),
         hookSessionPrefix: DEFAULT_HOOK_SESSION_PREFIX,
         hookRelayDedupeWindowMs: DEFAULT_RELAY_DEDUPE_WINDOW_MS,
         hookResponseTimeoutMs: DEFAULT_HOOK_RESPONSE_TIMEOUT_MS,
@@ -606,11 +710,24 @@ export function createSentinelPlugin(overrides) {
             const headers = { "content-type": "application/json" };
             if (config.dispatchAuthToken)
                 headers.authorization = `Bearer ${config.dispatchAuthToken}`;
-            await fetch(`${config.localDispatchBase}${path}`, {
+            const response = await fetch(`${config.localDispatchBase}${path}`, {
                 method: "POST",
                 headers,
                 body: JSON.stringify(body),
             });
+            if (!response.ok) {
+                let responseBody = "";
+                try {
+                    responseBody = await response.text();
+                }
+                catch {
+                    responseBody = "";
+                }
+                const details = responseBody ? ` body=${trimText(responseBody, 256)}` : "";
+                const error = new Error(`dispatch failed with status ${response.status}${details}`);
+                error.status = response.status;
+                throw error;
+            }
         },
     });
     return {
@@ -622,11 +739,18 @@ export function createSentinelPlugin(overrides) {
             const runtimeConfig = resolveSentinelPluginConfig(api);
             if (Object.keys(runtimeConfig).length > 0)
                 Object.assign(config, runtimeConfig);
-            const hookResponseRelayManager = new HookResponseRelayManager(config, api);
-            if (typeof api.on === "function") {
-                api.on("llm_output", (event, ctx) => {
-                    void hookResponseRelayManager.handleLlmOutput(ctx?.sessionKey, event.assistantTexts);
-                });
+            config.dispatchAuthToken = asString(config.dispatchAuthToken);
+            manager.setLogger(api.logger);
+            if (Array.isArray(config.allowedHosts) && config.allowedHosts.length === 0) {
+                api.logger?.warn?.("[openclaw-sentinel] allowedHosts is empty. Watcher creation will fail until at least one host is configured.");
+            }
+            const hasLegacyHookSessionKey = !!asString(config.hookSessionKey);
+            const hasCustomHookSessionPrefix = !!asString(config.hookSessionPrefix) &&
+                asString(config.hookSessionPrefix) !== DEFAULT_HOOK_SESSION_PREFIX;
+            if (hasLegacyHookSessionKey) {
+                api.logger?.warn?.(hasCustomHookSessionPrefix
+                    ? "[openclaw-sentinel] hookSessionKey is deprecated and ignored when hookSessionPrefix is set. Remove hookSessionKey from config."
+                    : "[openclaw-sentinel] hookSessionKey is deprecated. Rename it to hookSessionPrefix.");
             }
             manager.setNotifier({
                 async notify(target, message) {
@@ -648,6 +772,12 @@ export function createSentinelPlugin(overrides) {
                 manager.setWebhookRegistrationStatus("ok", "Route already registered (idempotent)", path);
                 return;
             }
+            const hookResponseRelayManager = new HookResponseRelayManager(config, api);
+            if (typeof api.on === "function") {
+                api.on("llm_output", (event, ctx) => {
+                    void hookResponseRelayManager.handleLlmOutput(ctx?.sessionKey, event.assistantTexts);
+                });
+            }
             try {
                 api.registerHttpRoute({
                     path,
@@ -693,7 +823,14 @@ export function createSentinelPlugin(overrides) {
                             const message = String(err?.message ?? err);
                             const badRequest = message.includes("Invalid JSON payload") ||
                                 message.includes("Payload must be a JSON object");
-                            const status = message.includes("too large") ? 413 : badRequest ? 400 : 500;
+                            const unsupportedMediaType = message.includes("Unsupported Content-Type");
+                            const status = message.includes("too large")
+                                ? 413
+                                : unsupportedMediaType
+                                    ? 415
+                                    : badRequest
+                                        ? 400
+                                        : 500;
                             res.writeHead(status, { "content-type": "application/json" });
                             res.end(JSON.stringify({ error: message }));
                         }
@@ -704,6 +841,7 @@ export function createSentinelPlugin(overrides) {
                 api.logger?.info?.(`[openclaw-sentinel] Registered default webhook route ${path}`);
             }
             catch (err) {
+                hookResponseRelayManager.dispose();
                 const msg = `Failed to register default webhook route ${path}: ${String(err?.message ?? err)}`;
                 manager.setWebhookRegistrationStatus("error", msg, path);
                 api.logger?.error?.(`[openclaw-sentinel] ${msg}`);
@@ -719,8 +857,8 @@ const sentinelPlugin = {
     configSchema: sentinelConfigSchema,
     register(api) {
         const plugin = createSentinelPlugin(api.pluginConfig);
-        void plugin.init();
         plugin.register(api);
+        void plugin.init();
     },
 };
 export const register = sentinelPlugin.register.bind(sentinelPlugin);

package/dist/strategies/httpLongPoll.js

@@ -1,29 +1,55 @@
+function isAbortError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.name === "AbortError" || err.message.toLowerCase().includes("aborted");
+}
 export const httpLongPollStrategy = async (watcher, onPayload, onError) => {
     let active = true;
+    let inFlightAbort;
     const loop = async () => {
         while (active) {
             try {
+                inFlightAbort = new AbortController();
                 const response = await fetch(watcher.endpoint, {
                     method: watcher.method ?? "GET",
                     headers: watcher.headers,
                     body: watcher.body,
-                    signal: AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                    signal: AbortSignal.any([
+                        inFlightAbort.signal,
+                        AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                    ]),
+                    redirect: "error",
                 });
                 if (!response.ok)
                     throw new Error(`http-long-poll non-2xx: ${response.status}`);
                 const contentType = response.headers.get("content-type") ?? "";
-                if (!contentType.toLowerCase().includes("json"))
+                if (!contentType.toLowerCase().includes("json")) {
                     throw new Error(`http-long-poll expected JSON, got: ${contentType || "unknown"}`);
-                await onPayload(await response.json());
+                }
+                let payload;
+                try {
+                    payload = await response.json();
+                }
+                catch (err) {
+                    throw new Error(`http-long-poll invalid JSON response: ${String(err?.message ?? err)}`);
+                }
+                await onPayload(payload);
             }
             catch (err) {
+                if (!active && isAbortError(err))
+                    return;
                 await onError(err);
                 return;
             }
+            finally {
+                inFlightAbort = undefined;
+            }
         }
     };
     void loop();
     return async () => {
         active = false;
+        inFlightAbort?.abort();
+        inFlightAbort = undefined;
     };
 };

package/dist/strategies/httpPoll.js

@@ -1,35 +1,66 @@
+function isAbortError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.name === "AbortError" || err.message.toLowerCase().includes("aborted");
+}
 export const httpPollStrategy = async (watcher, onPayload, onError) => {
     const interval = watcher.intervalMs ?? 30000;
     let active = true;
+    let timer;
+    let inFlightAbort;
     const tick = async () => {
         if (!active)
             return;
         try {
+            inFlightAbort = new AbortController();
             const response = await fetch(watcher.endpoint, {
                 method: watcher.method ?? "GET",
                 headers: watcher.headers,
                 body: watcher.body,
-                signal: AbortSignal.timeout(watcher.timeoutMs ?? 15000),
+                signal: AbortSignal.any([
+                    inFlightAbort.signal,
+                    AbortSignal.timeout(watcher.timeoutMs ?? 15000),
+                ]),
+                redirect: "error",
             });
             if (!response.ok)
                 throw new Error(`http-poll non-2xx: ${response.status}`);
             const contentType = response.headers.get("content-type") ?? "";
-            if (!contentType.toLowerCase().includes("json"))
+            if (!contentType.toLowerCase().includes("json")) {
                 throw new Error(`http-poll expected JSON, got: ${contentType || "unknown"}`);
-            const payload = await response.json();
+            }
+            let payload;
+            try {
+                payload = await response.json();
+            }
+            catch (err) {
+                throw new Error(`http-poll invalid JSON response: ${String(err?.message ?? err)}`);
+            }
             await onPayload(payload);
         }
         catch (err) {
+            if (!active && isAbortError(err))
+                return;
             await onError(err);
             return;
         }
-        if (active)
-            setTimeout(() => {
+        finally {
+            inFlightAbort = undefined;
+        }
+        if (active) {
+            timer = setTimeout(() => {
                 void tick();
             }, interval);
+        }
     };
     void tick();
     return async () => {
         active = false;
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        inFlightAbort?.abort();
+        inFlightAbort = undefined;
     };
 };

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.6.0",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",