@coffeexdev/openclaw-sentinel 0.5.1 → 0.7.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
@@ -146,10 +154,10 @@ Use `sentinel_control`:
 1. Sentinel evaluates conditions.
 2. On match, it dispatches a generic callback envelope (`type: "sentinel.callback"`) to `localDispatchBase + webhookPath`.
 3. The envelope includes stable keys (`intent`, `context`, `watcher`, `trigger`, bounded `payload`, `deliveryTargets`, `deliveryContext`, `source`) so downstream agent behavior is workflow-agnostic.
-4. For `/hooks/sentinel`, Sentinel enqueues an instruction-prefixed system event plus structured JSON envelope with a cron-tagged callback context, then requests an immediate `cron:sentinel-callback` wake (avoids heartbeat-poll prompting).
+4. For `/hooks/sentinel`, Sentinel enqueues an instruction-prefixed system event with a **structured callback prompt context** (`watcher`, `trigger`, `source`, `deliveryTargets`, `deliveryContext`, `context`, `payload`) plus the full envelope, then requests an immediate `cron:sentinel-callback` wake (avoids heartbeat-poll prompting).
 5. The hook route creates a **response-delivery contract** keyed by callback dedupe key, preserving original chat/session context (`deliveryContext`) and intended relay targets.
 6. OpenClaw processes each callback in an isolated hook session: per-watcher by default, or grouped when `hookSessionGroup` / `fire.sessionGroup` is set. Shared global hook-session mode is intentionally not supported.
-7. When hook-session LLM output arrives, Sentinel relays assistant-authored text to the original chat context. If no assistant output arrives before `hookResponseTimeoutMs`, optional fallback relay behavior is applied (`hookResponseFallbackMode`).
+7. Relay guardrails suppress control-token outputs (`NO_REPLY`, `HEARTBEAT_OK`, empty variants). If model output is unusable, Sentinel emits a concise contextual fallback message. Timeout fallback behavior still follows `hookResponseFallbackMode`.
 
 The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent). Response contracts are dedupe-aware by callback dedupe key (`hookResponseDedupeWindowMs`).
 
@@ -161,7 +169,17 @@ Sample emitted envelope:
   "version": "1",
   "intent": "price_threshold_review",
   "actionable": true,
-  "watcher": { "id": "eth-price-watch", "skillId": "skills.alerts", "eventName": "eth_target_hit" },
+  "watcher": {
+    "id": "eth-price-watch",
+    "skillId": "skills.alerts",
+    "eventName": "eth_target_hit",
+    "intent": "price_threshold_review",
+    "strategy": "http-poll",
+    "endpoint": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd",
+    "match": "all",
+    "conditions": [{ "path": "ethereum.usd", "op": "gte", "value": 5000 }],
+    "fireOnce": false
+  },
   "trigger": {
     "matchedAt": "2026-03-04T15:00:00.000Z",
     "dedupeKey": "<sha256>",
@@ -257,9 +275,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 +293,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 +311,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",
+        },
+      },
+    },
   },
 }
 ```
@@ -334,10 +373,11 @@ Precedence: **watcher override > global setting**.
 1. Callback is enqueued to isolated hook session.
 2. Contract captures original delivery context (`deliveryContext` + resolved `deliveryTargets`).
 3. First assistant-authored `llm_output` for that pending callback is relayed to target chat.
-4. If no assistant output arrives in time (`hookResponseTimeoutMs`), fallback is configurable:
+4. Reserved control outputs are never relayed (`NO_REPLY`, `HEARTBEAT_OK`, empty variants). If output is unusable, Sentinel sends a concise contextual guardrail fallback.
+5. If no assistant output arrives in time (`hookResponseTimeoutMs`), timeout fallback is configurable:
    - `hookResponseFallbackMode: "concise"` (default) sends a short fail-safe relay.
-   - `hookResponseFallbackMode: "none"` suppresses fallback.
-5. Repeated callbacks with same dedupe key are idempotent within `hookResponseDedupeWindowMs`.
+   - `hookResponseFallbackMode: "none"` suppresses timeout fallback.
+6. Repeated callbacks with same dedupe key are idempotent within `hookResponseDedupeWindowMs`.
 
 Example config:
 

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;
@@ -110,6 +108,12 @@ export function createCallbackEnvelope(args) {
             id: watcher.id,
             skillId: watcher.skillId,
             eventName: watcher.fire.eventName,
+            intent,
+            strategy: watcher.strategy,
+            endpoint: watcher.endpoint,
+            match: watcher.match,
+            conditions: watcher.conditions,
+            fireOnce: watcher.fireOnce ?? false,
         },
         trigger: {
             matchedAt,

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");