@coffeexdev/openclaw-sentinel 0.6.0 → 0.7.0

package/README.md

@@ -154,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`).
 
@@ -169,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>",
@@ -363,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

@@ -108,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/index.js

@@ -14,8 +14,8 @@ const MAX_SENTINEL_WEBHOOK_TEXT_CHARS = 8000;
 const MAX_SENTINEL_PAYLOAD_JSON_CHARS = 2500;
 const SENTINEL_CALLBACK_WAKE_REASON = "cron:sentinel-callback";
 const SENTINEL_CALLBACK_CONTEXT_KEY = "cron:sentinel-callback";
-const HEARTBEAT_ACK_TOKEN_PATTERN = /\bHEARTBEAT_OK\b/gi;
-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 RESERVED_CONTROL_TOKEN_PATTERN = /\b(?:NO[\s_-]*REPLY|HEARTBEAT[\s_-]*OK)\b/gi;
+const SENTINEL_EVENT_INSTRUCTION_PREFIX = "SENTINEL_TRIGGER: This system event came from /hooks/sentinel. Use watcher + payload context to decide safe follow-up actions and produce a user-facing response.";
 const SUPPORTED_DELIVERY_CHANNELS = new Set([
     "telegram",
     "discord",
@@ -165,25 +165,26 @@ function extractDeliveryContext(payload) {
         context.deliveryTargets = deliveryTargets;
     return Object.keys(context).length > 0 ? context : undefined;
 }
+function asBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
 function buildSentinelEventEnvelope(payload) {
+    const watcherRecord = isRecord(payload.watcher) ? payload.watcher : undefined;
+    const triggerRecord = isRecord(payload.trigger) ? payload.trigger : undefined;
     const watcherId = asString(payload.watcherId) ??
-        getNestedString(payload, ["watcher", "id"]) ??
+        asString(watcherRecord?.id) ??
         getNestedString(payload, ["context", "watcherId"]);
     const eventName = asString(payload.eventName) ??
-        getNestedString(payload, ["watcher", "eventName"]) ??
+        asString(watcherRecord?.eventName) ??
         getNestedString(payload, ["event", "name"]);
     const skillId = asString(payload.skillId) ??
-        getNestedString(payload, ["watcher", "skillId"]) ??
+        asString(watcherRecord?.skillId) ??
         getNestedString(payload, ["context", "skillId"]) ??
         undefined;
     const matchedAt = asIsoString(payload.matchedAt) ??
         asIsoString(payload.timestamp) ??
-        asIsoString(getNestedString(payload, ["trigger", "matchedAt"])) ??
+        asIsoString(triggerRecord?.matchedAt) ??
         new Date().toISOString();
-    const rawPayload = payload.payload ??
-        (isRecord(payload.event) ? (payload.event.payload ?? payload.event.data) : undefined) ??
-        payload;
-    const boundedPayload = clipPayloadForPrompt(rawPayload);
     const dedupeSeed = JSON.stringify({
         watcherId: watcherId ?? null,
         eventName: eventName ?? null,
@@ -193,8 +194,15 @@ function buildSentinelEventEnvelope(payload) {
     const dedupeKey = asString(payload.dedupeKey) ??
         asString(payload.correlationId) ??
         asString(payload.correlationID) ??
-        getNestedString(payload, ["trigger", "dedupeKey"]) ??
+        asString(triggerRecord?.dedupeKey) ??
         generatedDedupe;
+    const rawPayload = payload.payload ??
+        (isRecord(payload.event) ? (payload.event.payload ?? payload.event.data) : undefined) ??
+        payload;
+    const rawContext = payload.context ??
+        (isRecord(rawPayload) ? rawPayload.context : undefined) ??
+        (isRecord(payload.event) ? payload.event.context : undefined) ??
+        null;
     const deliveryTargets = Array.isArray(payload.deliveryTargets)
         ? payload.deliveryTargets.filter(isDeliveryTarget)
         : undefined;
@@ -202,13 +210,41 @@ function buildSentinelEventEnvelope(payload) {
     const sourcePlugin = getNestedString(payload, ["source", "plugin"]) ?? "openclaw-sentinel";
     const hookSessionGroup = asString(payload.hookSessionGroup) ??
         asString(payload.sessionGroup) ??
-        getNestedString(payload, ["watcher", "sessionGroup"]);
+        asString(watcherRecord?.sessionGroup);
     const deliveryContext = extractDeliveryContext(payload);
+    const watcherIntent = asString(payload.intent) ?? asString(watcherRecord?.intent) ?? null;
+    const watcherStrategy = asString(watcherRecord?.strategy) ?? asString(payload.strategy) ?? null;
+    const watcherEndpoint = asString(watcherRecord?.endpoint) ?? asString(payload.endpoint) ?? null;
+    const watcherMatch = asString(watcherRecord?.match) ?? asString(payload.match) ?? null;
+    const watcherConditions = Array.isArray(watcherRecord?.conditions)
+        ? watcherRecord.conditions
+        : Array.isArray(payload.conditions)
+            ? payload.conditions
+            : [];
+    const watcherFireOnce = asBoolean(watcherRecord?.fireOnce ?? payload.fireOnce) ?? null;
+    const triggerPriority = asString(payload.priority) ?? asString(triggerRecord?.priority) ?? null;
     const envelope = {
         watcherId: watcherId ?? null,
         eventName: eventName ?? null,
         matchedAt,
-        payload: boundedPayload,
+        watcher: {
+            id: watcherId ?? null,
+            skillId: skillId ?? null,
+            eventName: eventName ?? null,
+            intent: watcherIntent,
+            strategy: watcherStrategy,
+            endpoint: watcherEndpoint,
+            match: watcherMatch,
+            conditions: watcherConditions,
+            fireOnce: watcherFireOnce,
+        },
+        trigger: {
+            matchedAt,
+            dedupeKey,
+            priority: triggerPriority,
+        },
+        context: clipPayloadForPrompt(rawContext),
+        payload: clipPayloadForPrompt(rawPayload),
         dedupeKey,
         correlationId: dedupeKey,
         source: {
@@ -227,8 +263,26 @@ function buildSentinelEventEnvelope(payload) {
     return envelope;
 }
 function buildSentinelSystemEvent(envelope) {
-    const jsonEnvelope = JSON.stringify(envelope, null, 2);
-    const text = `${SENTINEL_EVENT_INSTRUCTION_PREFIX}\nSENTINEL_ENVELOPE_JSON:\n${jsonEnvelope}`;
+    const callbackContext = {
+        watcher: envelope.watcher,
+        trigger: envelope.trigger,
+        source: envelope.source,
+        deliveryTargets: envelope.deliveryTargets ?? [],
+        deliveryContext: envelope.deliveryContext ?? null,
+        context: envelope.context,
+        payload: envelope.payload,
+    };
+    const text = [
+        SENTINEL_EVENT_INSTRUCTION_PREFIX,
+        "Callback handling requirements:",
+        "- Base actions on watcher intent/event/skill plus the callback context and payload.",
+        "- Return a concise user-facing response that reflects what triggered and what to do next.",
+        "- Never emit control tokens such as NO_REPLY or HEARTBEAT_OK.",
+        "SENTINEL_CALLBACK_CONTEXT_JSON:",
+        JSON.stringify(callbackContext, null, 2),
+        "SENTINEL_ENVELOPE_JSON:",
+        JSON.stringify(envelope, null, 2),
+    ].join("\n");
     return trimText(text, MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
 }
 function normalizeDeliveryTargets(targets) {
@@ -329,9 +383,11 @@ function summarizeContext(value) {
 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 intent = envelope.watcher.intent ? `intent ${envelope.watcher.intent}` : undefined;
+    const contextSummary = summarizeContext(envelope.context) ?? summarizeContext(envelope.payload);
     const lines = [title, `${watcher} · ${envelope.matchedAt}`];
+    if (intent)
+        lines.push(intent);
     if (contextSummary)
         lines.push(contextSummary);
     const text = lines.join("\n").trim();
@@ -339,12 +395,25 @@ function buildRelayMessage(envelope) {
         ? text
         : "Sentinel callback received, but no assistant detail was generated.";
 }
+function normalizeControlTokenCandidate(value) {
+    return value.replace(/[^a-zA-Z]/g, "").toUpperCase();
+}
+function sanitizeAssistantRelaySegment(value) {
+    if (typeof value !== "string")
+        return "";
+    const tokenCandidate = normalizeControlTokenCandidate(value.trim());
+    if (tokenCandidate === "NOREPLY" || tokenCandidate === "HEARTBEATOK")
+        return "";
+    const withoutTokens = value.replace(RESERVED_CONTROL_TOKEN_PATTERN, " ").trim();
+    if (!withoutTokens)
+        return "";
+    const collapsed = withoutTokens.replace(/\s+/g, " ").trim();
+    return /[a-zA-Z0-9]/.test(collapsed) ? collapsed : "";
+}
 function normalizeAssistantRelayText(assistantTexts) {
     if (!Array.isArray(assistantTexts) || assistantTexts.length === 0)
         return undefined;
-    const parts = assistantTexts
-        .map((value) => value.replace(HEARTBEAT_ACK_TOKEN_PATTERN, "").trim())
-        .filter(Boolean);
+    const parts = assistantTexts.map(sanitizeAssistantRelaySegment).filter(Boolean);
     if (parts.length === 0)
         return undefined;
     return trimText(parts.join("\n\n"), MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
@@ -573,8 +642,7 @@ class HookResponseRelayManager {
     async handleLlmOutput(sessionKey, assistantTexts) {
         if (!sessionKey)
             return;
-        const assistantMessage = normalizeAssistantRelayText(assistantTexts);
-        if (!assistantMessage)
+        if (!Array.isArray(assistantTexts) || assistantTexts.length === 0)
             return;
         const dedupeKey = this.popNextPendingDedupe(sessionKey);
         if (!dedupeKey)
@@ -582,7 +650,12 @@ class HookResponseRelayManager {
         const pending = this.pendingByDedupe.get(dedupeKey);
         if (!pending || pending.state !== "pending")
             return;
-        await this.completeWithMessage(pending, assistantMessage, "assistant");
+        const assistantMessage = normalizeAssistantRelayText(assistantTexts);
+        if (assistantMessage) {
+            await this.completeWithMessage(pending, assistantMessage, "assistant");
+            return;
+        }
+        await this.completeWithMessage(pending, pending.fallbackMessage, "guardrail");
     }
     dispose() {
         if (this.disposed)
@@ -675,7 +748,12 @@ class HookResponseRelayManager {
     async completeWithMessage(pending, message, source) {
         const delivery = await deliverMessageToTargets(this.api, pending.relayTargets, message);
         this.markClosed(pending, source === "assistant" ? "completed" : "timed_out");
-        this.api.logger?.info?.(`[openclaw-sentinel] ${source === "assistant" ? "Relayed assistant response" : "Sent timeout fallback"} for dedupe=${pending.dedupeKey} delivered=${delivery.delivered} failed=${delivery.failed}`);
+        const action = source === "assistant"
+            ? "Relayed assistant response"
+            : source === "guardrail"
+                ? "Sent guardrail fallback"
+                : "Sent timeout fallback";
+        this.api.logger?.info?.(`[openclaw-sentinel] ${action} for dedupe=${pending.dedupeKey} delivered=${delivery.delivered} failed=${delivery.failed}`);
     }
     markClosed(pending, state) {
         pending.state = state;

package/package.json

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