@coffeexdev/openclaw-sentinel 0.4.4 → 0.4.5

package/README.md

@@ -18,19 +18,42 @@ Add/update `~/.openclaw/openclaw.json`:
 
 ```json5
 {
-  sentinel: {
-    // Required: watchers can only call endpoints on these hosts.
-    allowedHosts: ["api.github.com", "api.coingecko.com"],
-
-    // Default dispatch base for internal webhook callbacks.
-    localDispatchBase: "http://127.0.0.1:18789",
-
-    // Optional: where /hooks/sentinel events are queued in the LLM loop.
-    hookSessionKey: "agent:main:main",
-
-    // Optional: bearer token used for dispatch calls back to gateway.
-    // Set this to your gateway auth token when gateway auth is enabled.
-    // dispatchAuthToken: "<gateway-token>"
+  plugins: {
+    entries: {
+      "openclaw-sentinel": {
+        enabled: true,
+        config: {
+          // Required: watchers can only call endpoints on these hosts.
+          allowedHosts: ["api.github.com", "api.coingecko.com"],
+
+          // Default dispatch base for internal webhook callbacks.
+          localDispatchBase: "http://127.0.0.1:18789",
+
+          // Optional: base prefix for isolated /hooks/sentinel callback sessions.
+          // Sentinel appends :watcher:<id> by default (or :group:<key> when grouped).
+          hookSessionPrefix: "agent:main:hooks:sentinel",
+
+          // Optional: default group key for callbacks without explicit hookSessionGroup.
+          // hookSessionGroup: "ops-alerts",
+
+          // Optional: suppress duplicate relays by dedupe key within this time window.
+          hookRelayDedupeWindowMs: 120000,
+
+          // Optional: payload style for non-/hooks/sentinel deliveryTargets notifications.
+          // "none" suppresses delivery-target message fan-out (callback still fires).
+          // "concise" (default) sends human-friendly relay text only.
+          // "debug" appends a structured sentinel envelope block for diagnostics.
+          // notificationPayloadMode: "concise",
+
+          // 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.
+          // dispatchAuthToken: "<gateway-token>"
+        },
+      },
+    },
   },
 }
 ```
@@ -41,6 +64,20 @@ Add/update `~/.openclaw/openclaw.json`:
 openclaw gateway restart
 ```
 
+### Troubleshooting: `Unrecognized key: "sentinel"`
+
+If gateway startup/validation reports:
+
+```text
+Unrecognized key: "sentinel"
+```
+
+your config is using the old root-level shape. Move Sentinel config under:
+
+- `plugins.entries.openclaw-sentinel.config`
+
+Sentinel also logs a runtime warning when that legacy root key is still observable, but it never writes a root-level `sentinel` key.
+
 ### 4) Create your first watcher (`sentinel_control`)
 
 ```json
@@ -65,6 +102,7 @@ openclaw gateway restart
         "workflow": "alerts"
       },
       "priority": "high",
+      "sessionGroup": "portfolio-risk",
       "deadlineTemplate": "${timestamp}",
       "payloadTemplate": {
         "event": "${event.name}",
@@ -97,11 +135,11 @@ 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`, `source`) so downstream agent behavior is workflow-agnostic.
-4. It also sends a notification message to each configured `deliveryTargets` destination (defaults to the current chat context when watcher is created from a channel session).
-5. For `/hooks/sentinel`, the plugin route enqueues an instruction-prefixed system event plus structured JSON envelope and requests heartbeat wake.
-6. OpenClaw wakes and processes that event in the configured session (`hookSessionKey`, default `agent:main:main`).
+4. For `/hooks/sentinel`, delivery to user chat is relayed from the hook route using `deliveryTargets` (or inferred chat context when available) with a concise alert message.
+5. The `/hooks/sentinel` route enqueues an instruction-prefixed system event plus structured JSON envelope and requests heartbeat wake.
+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.
 
-The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent).
+The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent). Relay notifications are dedupe-aware by callback dedupe key.
 
 Sample emitted envelope:
 
@@ -185,6 +223,91 @@ It **does not** execute user-authored code from watcher definitions.
 
 `deliveryTargets` is optional. If omitted on `create`, Sentinel infers a default target from the current tool/session context (channel + current peer).
 
+## Notification payload delivery modes
+
+Sentinel always dispatches the callback envelope to `localDispatchBase + webhookPath` on match.
+`notificationPayloadMode` only controls **additional fan-out messages** to `deliveryTargets`.
+
+Global mode options:
+
+- `none`: suppress delivery-target notification messages (callback dispatch still occurs)
+- `concise` (default): send short relay text only
+- `debug`: send relay text plus `SENTINEL_DEBUG_ENVELOPE_JSON` block
+
+### 1) Global notifications disabled (`none`)
+
+```json5
+{
+  sentinel: {
+    allowedHosts: ["api.github.com"],
+    notificationPayloadMode: "none",
+  },
+}
+```
+
+### 2) Global concise relay (default)
+
+```json5
+{
+  sentinel: {
+    allowedHosts: ["api.github.com"],
+    notificationPayloadMode: "concise",
+  },
+}
+```
+
+### 3) Global debug diagnostics
+
+```json5
+{
+  sentinel: {
+    allowedHosts: ["api.github.com"],
+    notificationPayloadMode: "debug",
+  },
+}
+```
+
+In debug mode, delivery notifications include the same concise relay line plus a `SENTINEL_DEBUG_ENVELOPE_JSON` block for diagnostics.
+
+### 4) Per-watcher override (`watcher.fire.notificationPayloadMode`)
+
+```json
+{
+  "action": "create",
+  "watcher": {
+    "id": "status-watch",
+    "skillId": "skills.ops",
+    "enabled": true,
+    "strategy": "http-poll",
+    "endpoint": "https://status.example.com/api/health",
+    "intervalMs": 10000,
+    "match": "all",
+    "conditions": [{ "path": "status", "op": "eq", "value": "degraded" }],
+    "fire": {
+      "webhookPath": "/hooks/agent",
+      "eventName": "service_degraded",
+      "notificationPayloadMode": "none",
+      "payloadTemplate": { "event": "${event.name}", "status": "${payload.status}" }
+    },
+    "retry": { "maxRetries": 5, "baseMs": 250, "maxMs": 5000 }
+  }
+}
+```
+
+Allowed values:
+
+- `inherit` (or omitted): follow global `notificationPayloadMode`
+- `none`: suppress delivery-target notification messages for this watcher
+- `concise`: force concise notification text for this watcher
+- `debug`: force debug envelope output for this watcher
+
+Precedence: **watcher override > global setting**.
+
+### Migration notes
+
+- Existing installs keep default behavior (`concise`) unless you set `notificationPayloadMode` explicitly.
+- If you want callback-only operation (wake LLM loop via `/hooks/sentinel` but no delivery-target chat message), set global or per-watcher mode to `none`.
+
 ## Runtime controls
 
 ```json

package/dist/callbackEnvelope.js

@@ -89,6 +89,7 @@ export function createCallbackEnvelope(args) {
             priority,
             ...(deadline ? { deadline } : {}),
         },
+        ...(watcher.fire.sessionGroup ? { hookSessionGroup: watcher.fire.sessionGroup } : {}),
         context: renderedContext ?? summarizePayload(payload),
         payload: truncatePayload(payload),
         deliveryTargets: watcher.deliveryTargets ?? [],

package/dist/configSchema.js

@@ -6,12 +6,21 @@ const LimitsSchema = Type.Object({
     maxConditionsPerWatcher: Type.Integer({ minimum: 1 }),
     maxIntervalMsFloor: Type.Integer({ minimum: 1 }),
 }, { additionalProperties: false });
+const NotificationPayloadModeSchema = Type.Union([
+    Type.Literal("none"),
+    Type.Literal("concise"),
+    Type.Literal("debug"),
+]);
 const ConfigSchema = Type.Object({
     allowedHosts: Type.Array(Type.String()),
     localDispatchBase: Type.String({ minLength: 1 }),
     dispatchAuthToken: Type.Optional(Type.String()),
     hookSessionKey: Type.Optional(Type.String({ minLength: 1 })),
+    hookSessionPrefix: Type.Optional(Type.String({ minLength: 1 })),
+    hookSessionGroup: Type.Optional(Type.String({ minLength: 1 })),
+    hookRelayDedupeWindowMs: Type.Optional(Type.Integer({ minimum: 0 })),
     stateFilePath: Type.Optional(Type.String()),
+    notificationPayloadMode: Type.Optional(NotificationPayloadModeSchema),
     limits: Type.Optional(LimitsSchema),
 }, { additionalProperties: false });
 function withDefaults(value) {
@@ -22,8 +31,18 @@ function withDefaults(value) {
             ? value.localDispatchBase
             : "http://127.0.0.1:18789",
         dispatchAuthToken: typeof value.dispatchAuthToken === "string" ? value.dispatchAuthToken : undefined,
-        hookSessionKey: typeof value.hookSessionKey === "string" ? value.hookSessionKey : "agent:main:main",
+        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,
         stateFilePath: typeof value.stateFilePath === "string" ? value.stateFilePath : undefined,
+        notificationPayloadMode: value.notificationPayloadMode === "none"
+            ? "none"
+            : value.notificationPayloadMode === "debug"
+                ? "debug"
+                : "concise",
         limits: {
             maxWatchersTotal: typeof limitsIn.maxWatchersTotal === "number" ? limitsIn.maxWatchersTotal : 200,
             maxWatchersPerSkill: typeof limitsIn.maxWatchersPerSkill === "number" ? limitsIn.maxWatchersPerSkill : 20,
@@ -96,13 +115,33 @@ export const sentinelConfigSchema = {
             },
             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,
@@ -148,8 +187,23 @@ export const sentinelConfigSchema = {
             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: {
@@ -157,6 +211,11 @@ export const sentinelConfigSchema = {
             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",

package/dist/index.js

@@ -4,11 +4,21 @@ import { registerSentinelControl } from "./tool.js";
 import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
 import { WatcherManager } from "./watcherManager.js";
 const registeredWebhookPathsByRegistrar = new WeakMap();
-const DEFAULT_HOOK_SESSION_KEY = "agent:main:main";
+const DEFAULT_HOOK_SESSION_PREFIX = "agent:main:hooks:sentinel";
+const DEFAULT_RELAY_DEDUPE_WINDOW_MS = 120_000;
 const MAX_SENTINEL_WEBHOOK_BODY_BYTES = 64 * 1024;
 const MAX_SENTINEL_WEBHOOK_TEXT_CHARS = 8000;
 const MAX_SENTINEL_PAYLOAD_JSON_CHARS = 2500;
 const SENTINEL_EVENT_INSTRUCTION_PREFIX = "SENTINEL_TRIGGER: This system event came from /hooks/sentinel. Evaluate action policy, decide whether to notify configured deliveryTargets, and execute safe follow-up actions.";
+const SUPPORTED_DELIVERY_CHANNELS = new Set([
+    "telegram",
+    "discord",
+    "slack",
+    "signal",
+    "imessage",
+    "whatsapp",
+    "line",
+]);
 function trimText(value, max) {
     return value.length <= max ? value : `${value.slice(0, max)}…`;
 }
@@ -28,6 +38,21 @@ function asIsoString(value) {
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
+function resolveSentinelPluginConfig(api) {
+    const pluginConfig = isRecord(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;
+}
 function isDeliveryTarget(value) {
     return (isRecord(value) &&
         typeof value.channel === "string" &&
@@ -41,6 +66,14 @@ function normalizePath(path) {
     const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
     return withSlash.length > 1 && withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
 }
+function sanitizeSessionSegment(value) {
+    const sanitized = value
+        .trim()
+        .replace(/[^a-zA-Z0-9_-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return sanitized.length > 0 ? sanitized.slice(0, 64) : "unknown";
+}
 function clipPayloadForPrompt(value) {
     const serialized = JSON.stringify(value);
     if (!serialized)
@@ -56,15 +89,30 @@ function clipPayloadForPrompt(value) {
         preview: `${clipped}…`,
     };
 }
+function getNestedString(value, path) {
+    let cursor = value;
+    for (const segment of path) {
+        if (!isRecord(cursor))
+            return undefined;
+        cursor = cursor[segment];
+    }
+    return asString(cursor);
+}
 function buildSentinelEventEnvelope(payload) {
     const watcherId = asString(payload.watcherId) ??
-        (isRecord(payload.watcher) ? asString(payload.watcher.id) : undefined);
+        getNestedString(payload, ["watcher", "id"]) ??
+        getNestedString(payload, ["context", "watcherId"]);
     const eventName = asString(payload.eventName) ??
-        (isRecord(payload.event) ? asString(payload.event.name) : undefined);
+        getNestedString(payload, ["watcher", "eventName"]) ??
+        getNestedString(payload, ["event", "name"]);
     const skillId = asString(payload.skillId) ??
-        (isRecord(payload.watcher) ? asString(payload.watcher.skillId) : undefined) ??
+        getNestedString(payload, ["watcher", "skillId"]) ??
+        getNestedString(payload, ["context", "skillId"]) ??
         undefined;
-    const matchedAt = asIsoString(payload.matchedAt) ?? asIsoString(payload.timestamp) ?? new Date().toISOString();
+    const matchedAt = asIsoString(payload.matchedAt) ??
+        asIsoString(payload.timestamp) ??
+        asIsoString(getNestedString(payload, ["trigger", "matchedAt"])) ??
+        new Date().toISOString();
     const rawPayload = payload.payload ??
         (isRecord(payload.event) ? (payload.event.payload ?? payload.event.data) : undefined) ??
         payload;
@@ -78,10 +126,16 @@ function buildSentinelEventEnvelope(payload) {
     const dedupeKey = asString(payload.dedupeKey) ??
         asString(payload.correlationId) ??
         asString(payload.correlationID) ??
+        getNestedString(payload, ["trigger", "dedupeKey"]) ??
         generatedDedupe;
     const deliveryTargets = Array.isArray(payload.deliveryTargets)
         ? payload.deliveryTargets.filter(isDeliveryTarget)
         : undefined;
+    const sourceRoute = getNestedString(payload, ["source", "route"]) ?? DEFAULT_SENTINEL_WEBHOOK_PATH;
+    const sourcePlugin = getNestedString(payload, ["source", "plugin"]) ?? "openclaw-sentinel";
+    const hookSessionGroup = asString(payload.hookSessionGroup) ??
+        asString(payload.sessionGroup) ??
+        getNestedString(payload, ["watcher", "sessionGroup"]);
     const envelope = {
         watcherId: watcherId ?? null,
         eventName: eventName ?? null,
@@ -90,22 +144,126 @@ function buildSentinelEventEnvelope(payload) {
         dedupeKey,
         correlationId: dedupeKey,
         source: {
-            route: DEFAULT_SENTINEL_WEBHOOK_PATH,
-            plugin: "openclaw-sentinel",
+            route: sourceRoute,
+            plugin: sourcePlugin,
         },
     };
     if (skillId)
         envelope.skillId = skillId;
+    if (hookSessionGroup)
+        envelope.hookSessionGroup = hookSessionGroup;
     if (deliveryTargets && deliveryTargets.length > 0)
         envelope.deliveryTargets = deliveryTargets;
     return envelope;
 }
-function buildSentinelSystemEvent(payload) {
-    const envelope = buildSentinelEventEnvelope(payload);
+function buildSentinelSystemEvent(envelope) {
     const jsonEnvelope = JSON.stringify(envelope, null, 2);
     const text = `${SENTINEL_EVENT_INSTRUCTION_PREFIX}\nSENTINEL_ENVELOPE_JSON:\n${jsonEnvelope}`;
     return trimText(text, MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
 }
+function normalizeDeliveryTargets(targets) {
+    const deduped = new Map();
+    for (const target of targets) {
+        const channel = asString(target.channel);
+        const to = asString(target.to);
+        if (!channel || !to || !SUPPORTED_DELIVERY_CHANNELS.has(channel))
+            continue;
+        const accountId = asString(target.accountId);
+        const key = `${channel}:${to}:${accountId ?? ""}`;
+        deduped.set(key, { channel, to, ...(accountId ? { accountId } : {}) });
+    }
+    return [...deduped.values()];
+}
+function inferTargetFromSessionKey(sessionKey, accountId) {
+    const segments = sessionKey
+        .split(":")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (segments.length < 5)
+        return undefined;
+    const channel = segments[2];
+    const to = segments.at(-1);
+    if (!channel || !to || !SUPPORTED_DELIVERY_CHANNELS.has(channel))
+        return undefined;
+    return {
+        channel,
+        to,
+        ...(accountId ? { accountId } : {}),
+    };
+}
+function inferRelayTargets(payload, envelope) {
+    if (envelope.deliveryTargets?.length) {
+        return normalizeDeliveryTargets(envelope.deliveryTargets);
+    }
+    const inferred = [];
+    if (isDeliveryTarget(payload.currentChat))
+        inferred.push(payload.currentChat);
+    const sourceCurrentChat = isRecord(payload.source) ? payload.source.currentChat : undefined;
+    if (isDeliveryTarget(sourceCurrentChat))
+        inferred.push(sourceCurrentChat);
+    const messageChannel = asString(payload.messageChannel);
+    const requesterSenderId = asString(payload.requesterSenderId);
+    if (messageChannel && requesterSenderId && SUPPORTED_DELIVERY_CHANNELS.has(messageChannel)) {
+        inferred.push({ channel: messageChannel, to: requesterSenderId });
+    }
+    const fromSessionKey = asString(payload.sessionKey);
+    if (fromSessionKey) {
+        const target = inferTargetFromSessionKey(fromSessionKey, asString(payload.agentAccountId));
+        if (target)
+            inferred.push(target);
+    }
+    const sourceSessionKey = getNestedString(payload, ["source", "sessionKey"]);
+    if (sourceSessionKey) {
+        const sourceAccountId = getNestedString(payload, ["source", "accountId"]);
+        const target = inferTargetFromSessionKey(sourceSessionKey, sourceAccountId);
+        if (target)
+            inferred.push(target);
+    }
+    return normalizeDeliveryTargets(inferred);
+}
+function summarizeContext(value) {
+    if (!isRecord(value))
+        return undefined;
+    const entries = Object.entries(value).slice(0, 3);
+    if (entries.length === 0)
+        return undefined;
+    const chunks = entries.map(([key, val]) => {
+        if (typeof val === "string")
+            return `${key}=${trimText(val, 64)}`;
+        if (typeof val === "number" || typeof val === "boolean")
+            return `${key}=${String(val)}`;
+        return `${key}=${trimText(JSON.stringify(val), 64)}`;
+    });
+    return chunks.join(" · ");
+}
+function buildRelayMessage(envelope) {
+    const title = envelope.eventName ? `Sentinel alert: ${envelope.eventName}` : "Sentinel alert";
+    const watcher = envelope.watcherId ? `watcher ${envelope.watcherId}` : "watcher unknown";
+    const payloadRecord = isRecord(envelope.payload) ? envelope.payload : undefined;
+    const contextSummary = summarizeContext(payloadRecord && isRecord(payloadRecord.context) ? payloadRecord.context : payloadRecord);
+    const lines = [title, `${watcher} · ${envelope.matchedAt}`];
+    if (contextSummary)
+        lines.push(contextSummary);
+    const text = lines.join("\n").trim();
+    return text.length > 0 ? text : "Sentinel callback received.";
+}
+function buildIsolatedHookSessionKey(envelope, config) {
+    const rawPrefix = asString(config.hookSessionKey) ??
+        asString(config.hookSessionPrefix) ??
+        DEFAULT_HOOK_SESSION_PREFIX;
+    const prefix = rawPrefix.replace(/:+$/g, "");
+    const group = asString(envelope.hookSessionGroup) ?? asString(config.hookSessionGroup);
+    if (group) {
+        return `${prefix}:group:${sanitizeSessionSegment(group)}`;
+    }
+    if (envelope.watcherId) {
+        return `${prefix}:watcher:${sanitizeSessionSegment(envelope.watcherId)}`;
+    }
+    if (envelope.dedupeKey) {
+        return `${prefix}:event:${sanitizeSessionSegment(envelope.dedupeKey.slice(0, 24))}`;
+    }
+    return `${prefix}:event:unknown`;
+}
 async function readSentinelWebhookPayload(req) {
     const preParsed = req.body;
     if (isRecord(preParsed))
@@ -183,7 +341,9 @@ export function createSentinelPlugin(overrides) {
         allowedHosts: [],
         localDispatchBase: "http://127.0.0.1:18789",
         dispatchAuthToken: process.env.SENTINEL_DISPATCH_TOKEN,
-        hookSessionKey: DEFAULT_HOOK_SESSION_KEY,
+        hookSessionPrefix: DEFAULT_HOOK_SESSION_PREFIX,
+        hookRelayDedupeWindowMs: DEFAULT_RELAY_DEDUPE_WINDOW_MS,
+        notificationPayloadMode: "concise",
         limits: {
             maxWatchersTotal: 200,
             maxWatchersPerSkill: 20,
@@ -192,6 +352,22 @@ export function createSentinelPlugin(overrides) {
         },
         ...overrides,
     };
+    const recentRelayByDedupe = new Map();
+    const shouldRelayForDedupe = (dedupeKey) => {
+        const windowMs = Math.max(0, config.hookRelayDedupeWindowMs ?? DEFAULT_RELAY_DEDUPE_WINDOW_MS);
+        if (windowMs === 0)
+            return true;
+        const now = Date.now();
+        for (const [key, ts] of recentRelayByDedupe.entries()) {
+            if (now - ts > windowMs)
+                recentRelayByDedupe.delete(key);
+        }
+        const prev = recentRelayByDedupe.get(dedupeKey);
+        if (typeof prev === "number" && now - prev <= windowMs)
+            return false;
+        recentRelayByDedupe.set(dedupeKey, now);
+        return true;
+    };
     const manager = new WatcherManager(config, {
         async dispatch(path, body) {
             const headers = { "content-type": "application/json" };
@@ -210,6 +386,9 @@ export function createSentinelPlugin(overrides) {
             await manager.init();
         },
         register(api) {
+            const runtimeConfig = resolveSentinelPluginConfig(api);
+            if (Object.keys(runtimeConfig).length > 0)
+                Object.assign(config, runtimeConfig);
             manager.setNotifier({
                 async notify(target, message) {
                     await notifyDeliveryTarget(api, target, message);
@@ -244,19 +423,46 @@ export function createSentinelPlugin(overrides) {
                         }
                         try {
                             const payload = await readSentinelWebhookPayload(req);
-                            const sessionKey = config.hookSessionKey ?? DEFAULT_HOOK_SESSION_KEY;
-                            const text = buildSentinelSystemEvent(payload);
+                            const envelope = buildSentinelEventEnvelope(payload);
+                            const sessionKey = buildIsolatedHookSessionKey(envelope, config);
+                            const text = buildSentinelSystemEvent(envelope);
                             const enqueued = api.runtime.system.enqueueSystemEvent(text, { sessionKey });
                             api.runtime.system.requestHeartbeatNow({
                                 reason: "hook:sentinel",
                                 sessionKey,
                             });
+                            const relayTargets = inferRelayTargets(payload, envelope);
+                            const relayMessage = buildRelayMessage(envelope);
+                            const relay = {
+                                dedupeKey: envelope.dedupeKey,
+                                attempted: relayTargets.length,
+                                delivered: 0,
+                                failed: 0,
+                                deduped: false,
+                            };
+                            if (relayTargets.length > 0) {
+                                if (!shouldRelayForDedupe(envelope.dedupeKey)) {
+                                    relay.deduped = true;
+                                }
+                                else {
+                                    await Promise.all(relayTargets.map(async (target) => {
+                                        try {
+                                            await notifyDeliveryTarget(api, target, relayMessage);
+                                            relay.delivered += 1;
+                                        }
+                                        catch {
+                                            relay.failed += 1;
+                                        }
+                                    }));
+                                }
+                            }
                             res.writeHead(200, { "content-type": "application/json" });
                             res.end(JSON.stringify({
                                 ok: true,
                                 route: path,
                                 sessionKey,
                                 enqueued,
+                                relay,
                             }));
                         }
                         catch (err) {

package/dist/toolSchema.d.ts

@@ -26,6 +26,8 @@ export declare const SentinelToolValidationSchema: import("@sinclair/typebox").T
             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").TNumber;
@@ -74,6 +76,8 @@ export declare const SentinelToolSchema: 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").TNumber;

package/dist/toolSchema.js

@@ -35,6 +35,17 @@ const FireConfigSchema = Type.Object({
     priority: Type.Optional(Type.Union([Type.Literal("low"), Type.Literal("normal"), Type.Literal("high"), Type.Literal("critical")], { description: "Callback urgency hint" })),
     deadlineTemplate: Type.Optional(Type.String({ description: "Optional templated deadline string for callback consumers" })),
     dedupeKeyTemplate: Type.Optional(Type.String({ description: "Optional template to derive deterministic trigger dedupe key" })),
+    notificationPayloadMode: Type.Optional(Type.Union([
+        Type.Literal("inherit"),
+        Type.Literal("none"),
+        Type.Literal("concise"),
+        Type.Literal("debug"),
+    ], {
+        description: "Notification payload mode override for deliveryTargets (inherit global default, suppress messages, concise relay text, or debug envelope block)",
+    })),
+    sessionGroup: Type.Optional(Type.String({
+        description: "Optional hook session group key. Watchers with the same key share one isolated callback-processing session.",
+    })),
 });
 const RetryPolicySchema = Type.Object({
     maxRetries: Type.Number({ description: "Maximum number of retry attempts" }),

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export interface Condition {
 }
 export declare const DEFAULT_SENTINEL_WEBHOOK_PATH = "/hooks/sentinel";
 export type PriorityLevel = "low" | "normal" | "high" | "critical";
+export type NotificationPayloadMode = "none" | "concise" | "debug";
+export type NotificationPayloadModeOverride = "inherit" | NotificationPayloadMode;
 export interface FireConfig {
     webhookPath?: string;
     eventName: string;
@@ -16,6 +18,8 @@ export interface FireConfig {
     priority?: PriorityLevel;
     deadlineTemplate?: string;
     dedupeKeyTemplate?: string;
+    notificationPayloadMode?: NotificationPayloadModeOverride;
+    sessionGroup?: string;
 }
 export interface RetryPolicy {
     maxRetries: number;
@@ -83,8 +87,13 @@ export interface SentinelConfig {
     allowedHosts: string[];
     localDispatchBase: string;
     dispatchAuthToken?: string;
+    /** @deprecated Backward-compatible alias for hookSessionPrefix. */
     hookSessionKey?: string;
+    hookSessionPrefix?: string;
+    hookSessionGroup?: string;
+    hookRelayDedupeWindowMs?: number;
     stateFilePath?: string;
+    notificationPayloadMode?: NotificationPayloadMode;
     limits: SentinelLimits;
 }
 export interface GatewayWebhookDispatcher {

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

@@ -21,13 +21,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,
@@ -73,8 +93,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 +117,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",

package/package.json

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