@coffeexdev/openclaw-sentinel 0.4.4 → 0.5.0

package/README.md

@@ -18,19 +18,53 @@ 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: guarantee hook-response delivery contract for /hooks/sentinel callbacks.
+          // Wait this long for assistant-authored output before fallback behavior applies.
+          hookResponseTimeoutMs: 30000,
+
+          // Optional: timeout fallback relay mode for /hooks/sentinel response contracts.
+          // "none" = no fallback message, "concise" = send a fail-safe relay line.
+          hookResponseFallbackMode: "concise",
+
+          // Optional: dedupe repeated callback response contracts by dedupe key.
+          hookResponseDedupeWindowMs: 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 +75,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 +113,7 @@ openclaw gateway restart
         "workflow": "alerts"
       },
       "priority": "high",
+      "sessionGroup": "portfolio-risk",
       "deadlineTemplate": "${timestamp}",
       "payloadTemplate": {
         "event": "${event.name}",
@@ -96,12 +145,13 @@ 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`).
+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 and requests heartbeat wake.
+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`).
 
-The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent).
+The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent). Response contracts are dedupe-aware by callback dedupe key (`hookResponseDedupeWindowMs`).
 
 Sample emitted envelope:
 
@@ -120,6 +170,12 @@ Sample emitted envelope:
   "context": { "asset": "ETH", "priceUsd": 5001, "workflow": "alerts" },
   "payload": { "ethereum": { "usd": 5001 } },
   "deliveryTargets": [{ "channel": "telegram", "to": "5613673222" }],
+  "deliveryContext": {
+    "sessionKey": "agent:main:telegram:direct:5613673222",
+    "messageChannel": "telegram",
+    "requesterSenderId": "5613673222",
+    "currentChat": { "channel": "telegram", "to": "5613673222" }
+  },
   "source": { "plugin": "openclaw-sentinel", "route": "/hooks/sentinel" }
 }
 ```
@@ -185,6 +241,124 @@ 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` for watcher dispatches (for example `/hooks/agent`).
+It does **not** control `/hooks/sentinel` hook-response contracts or assistant-output relay behavior.
+
+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`.
+
+## Hook-response delivery contract (`/hooks/sentinel`)
+
+`/hooks/sentinel` now enforces a dedicated trigger → LLM → user-visible relay contract:
+
+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:
+   - `hookResponseFallbackMode: "concise"` (default) sends a short fail-safe relay.
+   - `hookResponseFallbackMode: "none"` suppresses fallback.
+5. Repeated callbacks with same dedupe key are idempotent within `hookResponseDedupeWindowMs`.
+
+Example config:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "openclaw-sentinel": {
+        enabled: true,
+        config: {
+          allowedHosts: ["api.github.com"],
+          hookResponseTimeoutMs: 30000,
+          hookResponseFallbackMode: "concise",
+          hookResponseDedupeWindowMs: 120000,
+        },
+      },
+    },
+  },
+}
+```
+
 ## Runtime controls
 
 ```json

package/dist/callbackEnvelope.js

@@ -1,4 +1,5 @@
 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";
 const MAX_PAYLOAD_JSON_CHARS = 4000;
 function toIntent(eventName) {
@@ -30,6 +31,32 @@ function truncatePayload(payload) {
         preview: serialized.slice(0, MAX_PAYLOAD_JSON_CHARS),
     };
 }
+function buildDeliveryContextFromMetadata(watcher) {
+    const metadata = watcher.metadata;
+    if (!metadata)
+        return undefined;
+    const sessionKey = metadata[SENTINEL_ORIGIN_SESSION_KEY_METADATA]?.trim();
+    const channel = metadata[SENTINEL_ORIGIN_CHANNEL_METADATA]?.trim();
+    const to = metadata[SENTINEL_ORIGIN_TARGET_METADATA]?.trim();
+    const accountId = metadata[SENTINEL_ORIGIN_ACCOUNT_METADATA]?.trim();
+    const context = {};
+    if (sessionKey)
+        context.sessionKey = sessionKey;
+    if (channel)
+        context.messageChannel = channel;
+    if (to)
+        context.requesterSenderId = to;
+    if (accountId)
+        context.agentAccountId = accountId;
+    if (channel && to) {
+        context.currentChat = {
+            channel,
+            to,
+            ...(accountId ? { accountId } : {}),
+        };
+    }
+    return Object.keys(context).length > 0 ? context : undefined;
+}
 function getPath(obj, path) {
     return path.split(".").reduce((acc, part) => acc?.[part], obj);
 }
@@ -73,6 +100,7 @@ export function createCallbackEnvelope(args) {
     const dedupeSeed = getTemplateString(watcher.fire.dedupeKeyTemplate, context) ??
         `${watcher.id}|${watcher.fire.eventName}|${matchedAt}`;
     const dedupeKey = createHash("sha256").update(dedupeSeed).digest("hex");
+    const deliveryContext = buildDeliveryContextFromMetadata(watcher);
     return {
         type: "sentinel.callback",
         version: "1",
@@ -89,6 +117,8 @@ export function createCallbackEnvelope(args) {
             priority,
             ...(deadline ? { deadline } : {}),
         },
+        ...(watcher.fire.sessionGroup ? { hookSessionGroup: watcher.fire.sessionGroup } : {}),
+        ...(deliveryContext ? { deliveryContext } : {}),
         context: renderedContext ?? summarizePayload(payload),
         payload: truncatePayload(payload),
         deliveryTargets: watcher.deliveryTargets ?? [],

package/dist/configSchema.js

@@ -6,12 +6,25 @@ 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 HookResponseFallbackModeSchema = Type.Union([Type.Literal("none"), Type.Literal("concise")]);
 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 })),
+    hookResponseTimeoutMs: Type.Optional(Type.Integer({ minimum: 0 })),
+    hookResponseFallbackMode: Type.Optional(HookResponseFallbackModeSchema),
+    hookResponseDedupeWindowMs: 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 +35,23 @@ 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,
+        hookResponseTimeoutMs: typeof value.hookResponseTimeoutMs === "number" ? value.hookResponseTimeoutMs : 30000,
+        hookResponseFallbackMode: value.hookResponseFallbackMode === "none" ? "none" : "concise",
+        hookResponseDedupeWindowMs: typeof value.hookResponseDedupeWindowMs === "number"
+            ? value.hookResponseDedupeWindowMs
+            : 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 +124,51 @@ 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,
+            },
+            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,
             },
             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 +214,38 @@ 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,
+        },
+        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,
         },
         stateFilePath: {
@@ -157,6 +253,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",