@coffeexdev/openclaw-sentinel 0.4.4 → 0.5.0

package/dist/types.js

@@ -1 +1,5 @@
 export const DEFAULT_SENTINEL_WEBHOOK_PATH = "/hooks/sentinel";
+export const SENTINEL_ORIGIN_SESSION_KEY_METADATA = "openclaw.sentinel.origin.sessionKey";
+export const SENTINEL_ORIGIN_CHANNEL_METADATA = "openclaw.sentinel.origin.channel";
+export const SENTINEL_ORIGIN_TARGET_METADATA = "openclaw.sentinel.origin.to";
+export const SENTINEL_ORIGIN_ACCOUNT_METADATA = "openclaw.sentinel.origin.accountId";

package/dist/validator.d.ts

@@ -25,6 +25,8 @@ export declare const WatcherSchema: import("@sinclair/typebox").TObject<{
         priority: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"low">, import("@sinclair/typebox").TLiteral<"normal">, import("@sinclair/typebox").TLiteral<"high">, import("@sinclair/typebox").TLiteral<"critical">]>>;
         deadlineTemplate: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         dedupeKeyTemplate: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        notificationPayloadMode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"inherit">, import("@sinclair/typebox").TLiteral<"none">, import("@sinclair/typebox").TLiteral<"concise">, import("@sinclair/typebox").TLiteral<"debug">]>>;
+        sessionGroup: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>;
     retry: import("@sinclair/typebox").TObject<{
         maxRetries: import("@sinclair/typebox").TInteger;

package/dist/validator.js

@@ -54,6 +54,13 @@ export const WatcherSchema = Type.Object({
         ])),
         deadlineTemplate: Type.Optional(Type.String({ minLength: 1 })),
         dedupeKeyTemplate: Type.Optional(Type.String({ minLength: 1 })),
+        notificationPayloadMode: Type.Optional(Type.Union([
+            Type.Literal("inherit"),
+            Type.Literal("none"),
+            Type.Literal("concise"),
+            Type.Literal("debug"),
+        ])),
+        sessionGroup: Type.Optional(Type.String({ minLength: 1 })),
     }, { additionalProperties: false }),
     retry: Type.Object({
         maxRetries: Type.Integer({ minimum: 0, maximum: 20 }),

package/dist/watcherManager.js

@@ -10,6 +10,32 @@ import { sseStrategy } from "./strategies/sse.js";
 import { websocketStrategy } from "./strategies/websocket.js";
 import { DEFAULT_SENTINEL_WEBHOOK_PATH, } from "./types.js";
 export const RESET_BACKOFF_AFTER_MS = 60_000;
+const MAX_DEBUG_NOTIFICATION_CHARS = 7000;
+function trimForChat(text) {
+    if (text.length <= MAX_DEBUG_NOTIFICATION_CHARS)
+        return text;
+    return `${text.slice(0, MAX_DEBUG_NOTIFICATION_CHARS)}…`;
+}
+function resolveNotificationPayloadMode(config, watcher) {
+    const override = watcher.fire.notificationPayloadMode;
+    if (override === "none" || override === "concise" || override === "debug")
+        return override;
+    if (config.notificationPayloadMode === "none")
+        return "none";
+    return config.notificationPayloadMode === "debug" ? "debug" : "concise";
+}
+function buildDeliveryNotificationMessage(watcher, body, mode) {
+    const matchedAt = typeof body.trigger === "object" &&
+        body.trigger !== null &&
+        typeof body.trigger.matchedAt === "string"
+        ? body.trigger.matchedAt
+        : new Date().toISOString();
+    const concise = `Sentinel watcher "${watcher.id}" fired event "${watcher.fire.eventName}" at ${matchedAt}.`;
+    if (mode !== "debug")
+        return concise;
+    const envelopeJson = JSON.stringify(body, null, 2) ?? "{}";
+    return trimForChat(`${concise}\n\nSENTINEL_DEBUG_ENVELOPE_JSON:\n${envelopeJson}`);
+}
 export const backoff = (base, max, failures) => {
     const raw = Math.min(max, base * 2 ** failures);
     const jitter = Math.floor(raw * 0.25 * (Math.random() * 2 - 1));
@@ -188,9 +214,14 @@ export class WatcherManager {
                     webhookPath,
                 });
                 await this.dispatcher.dispatch(webhookPath, body);
-                if (watcher.deliveryTargets?.length && this.notifier) {
+                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 = JSON.stringify(body);
+                    const message = buildDeliveryNotificationMessage(watcher, body, deliveryMode);
                     const failures = [];
                     let successCount = 0;
                     await Promise.all(watcher.deliveryTargets.map(async (target) => {

package/openclaw.plugin.json

@@ -6,7 +6,9 @@
     "properties": {
       "allowedHosts": {
         "type": "array",
-        "items": { "type": "string" },
+        "items": {
+          "type": "string"
+        },
         "description": "Hostnames the watchers are permitted to connect to. Must be explicitly configured — no hosts are allowed by default.",
         "default": []
       },
@@ -21,13 +23,33 @@
       },
       "hookSessionKey": {
         "type": "string",
-        "description": "Session key used when /hooks/sentinel enqueues system events into the LLM loop",
-        "default": "agent:main:main"
+        "description": "Deprecated alias for hookSessionPrefix. Sentinel always appends watcher/group segments to prevent a shared global callback session."
+      },
+      "hookSessionPrefix": {
+        "type": "string",
+        "description": "Base session key prefix used for isolated /hooks/sentinel callback sessions (default: agent:main:hooks:sentinel)",
+        "default": "agent:main:hooks:sentinel"
+      },
+      "hookSessionGroup": {
+        "type": "string",
+        "description": "Optional default session group key. When set, callbacks without explicit hookSessionGroup are routed to this group session."
+      },
+      "hookRelayDedupeWindowMs": {
+        "type": "number",
+        "minimum": 0,
+        "description": "Suppress duplicate relay messages for the same dedupe key within this window (milliseconds)",
+        "default": 120000
       },
       "stateFilePath": {
         "type": "string",
         "description": "Custom path for the sentinel state persistence file"
       },
+      "notificationPayloadMode": {
+        "type": "string",
+        "enum": ["none", "concise", "debug"],
+        "description": "Controls delivery-target notifications: none (suppress message fan-out), concise relay text (default), or relay text with debug envelope payload",
+        "default": "concise"
+      },
       "limits": {
         "type": "object",
         "additionalProperties": false,
@@ -54,6 +76,24 @@
             "default": 1000
           }
         }
+      },
+      "hookResponseTimeoutMs": {
+        "type": "number",
+        "minimum": 0,
+        "description": "Milliseconds to wait for an assistant-authored hook response before optional fallback relay",
+        "default": 30000
+      },
+      "hookResponseFallbackMode": {
+        "type": "string",
+        "enum": ["none", "concise"],
+        "description": "Fallback behavior when no assistant response arrives before hookResponseTimeoutMs: none (silent timeout) or concise fail-safe relay",
+        "default": "concise"
+      },
+      "hookResponseDedupeWindowMs": {
+        "type": "number",
+        "minimum": 0,
+        "description": "Deduplicate hook response-delivery contracts by dedupe key within this window (milliseconds)",
+        "default": 120000
       }
     }
   },
@@ -73,8 +113,23 @@
       "placeholder": "sk-..."
     },
     "hookSessionKey": {
-      "label": "Sentinel Hook Session Key",
-      "help": "Session key that receives /hooks/sentinel callback events (default: agent:main:main)",
+      "label": "Hook Session Key (Deprecated)",
+      "help": "Deprecated alias for hookSessionPrefix. Sentinel appends watcher/group segments automatically.",
+      "advanced": true
+    },
+    "hookSessionPrefix": {
+      "label": "Hook Session Prefix",
+      "help": "Base prefix for isolated callback sessions (default: agent:main:hooks:sentinel)",
+      "advanced": true
+    },
+    "hookSessionGroup": {
+      "label": "Default Hook Session Group",
+      "help": "Optional default group key for callback sessions. Watchers with the same group share one isolated session.",
+      "advanced": true
+    },
+    "hookRelayDedupeWindowMs": {
+      "label": "Hook Relay Dedupe Window (ms)",
+      "help": "Suppress duplicate relay messages with the same dedupe key for this many milliseconds",
       "advanced": true
     },
     "stateFilePath": {
@@ -82,6 +137,11 @@
       "help": "Custom path for sentinel state persistence file",
       "advanced": true
     },
+    "notificationPayloadMode": {
+      "label": "Notification Payload Mode",
+      "help": "Choose none (suppress delivery-target messages), concise relay text (default), or include debug envelope payload",
+      "advanced": true
+    },
     "limits.maxWatchersTotal": {
       "label": "Max Watchers",
       "help": "Maximum total watchers across all skills",
@@ -101,6 +161,21 @@
       "label": "Min Poll Interval (ms)",
       "help": "Minimum allowed polling interval in milliseconds",
       "advanced": true
+    },
+    "hookResponseTimeoutMs": {
+      "label": "Hook Response Timeout (ms)",
+      "help": "How long to wait for assistant-authored hook output before optional fallback relay",
+      "advanced": true
+    },
+    "hookResponseFallbackMode": {
+      "label": "Hook Response Fallback Mode",
+      "help": "If timeout occurs, choose none (silent) or concise fail-safe relay",
+      "advanced": true
+    },
+    "hookResponseDedupeWindowMs": {
+      "label": "Hook Response Dedupe Window (ms)",
+      "help": "Deduplicate hook-response delivery contracts by dedupe key within this window",
+      "advanced": true
     }
   },
   "install": {

package/package.json

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