@coffeexdev/openclaw-sentinel 0.4.5 → 0.5.1

package/README.md

@@ -39,6 +39,17 @@ Add/update `~/.openclaw/openclaw.json`:
           // 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.
@@ -134,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. 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.
+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).
+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). Relay notifications are dedupe-aware by callback dedupe key.
+The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent). Response contracts are dedupe-aware by callback dedupe key (`hookResponseDedupeWindowMs`).
 
 Sample emitted envelope:
 
@@ -158,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" }
 }
 ```
@@ -226,7 +244,8 @@ It **does not** execute user-authored code from watcher definitions.
 ## Notification payload delivery modes
 
 Sentinel always dispatches the callback envelope to `localDispatchBase + webhookPath` on match.
-`notificationPayloadMode` only controls **additional fan-out messages** to `deliveryTargets`.
+`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:
 
@@ -308,6 +327,38 @@ Precedence: **watcher override > global setting**.
 - 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",
@@ -90,6 +118,7 @@ export function createCallbackEnvelope(args) {
             ...(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

@@ -11,6 +11,7 @@ const NotificationPayloadModeSchema = Type.Union([
     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 }),
@@ -19,6 +20,9 @@ const ConfigSchema = Type.Object({
     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),
@@ -37,6 +41,11 @@ function withDefaults(value) {
             : "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"
@@ -132,6 +141,24 @@ export const sentinelConfigSchema = {
                 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",
@@ -206,6 +233,21 @@ export const sentinelConfigSchema = {
             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: {
             label: "State File Path",
             help: "Custom path for sentinel state persistence file",

package/dist/index.js

@@ -1,14 +1,19 @@
 import { createHash } from "node:crypto";
 import { sentinelConfigSchema } from "./configSchema.js";
 import { registerSentinelControl } from "./tool.js";
-import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
+import { DEFAULT_SENTINEL_WEBHOOK_PATH, } from "./types.js";
 import { WatcherManager } from "./watcherManager.js";
 const registeredWebhookPathsByRegistrar = new WeakMap();
 const DEFAULT_HOOK_SESSION_PREFIX = "agent:main:hooks:sentinel";
 const DEFAULT_RELAY_DEDUPE_WINDOW_MS = 120_000;
+const DEFAULT_HOOK_RESPONSE_TIMEOUT_MS = 30_000;
+const DEFAULT_HOOK_RESPONSE_FALLBACK_MODE = "concise";
 const MAX_SENTINEL_WEBHOOK_BODY_BYTES = 64 * 1024;
 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 SUPPORTED_DELIVERY_CHANNELS = new Set([
     "telegram",
@@ -98,6 +103,39 @@ function getNestedString(value, path) {
     }
     return asString(cursor);
 }
+function extractDeliveryContext(payload) {
+    const raw = isRecord(payload.deliveryContext) ? payload.deliveryContext : undefined;
+    if (!raw)
+        return undefined;
+    const sessionKey = asString(raw.sessionKey) ??
+        asString(raw.sourceSessionKey) ??
+        getNestedString(raw, ["source", "sessionKey"]);
+    const messageChannel = asString(raw.messageChannel);
+    const requesterSenderId = asString(raw.requesterSenderId);
+    const agentAccountId = asString(raw.agentAccountId);
+    const currentChat = isDeliveryTarget(raw.currentChat)
+        ? raw.currentChat
+        : isDeliveryTarget(raw.deliveryTarget)
+            ? raw.deliveryTarget
+            : undefined;
+    const deliveryTargets = Array.isArray(raw.deliveryTargets)
+        ? raw.deliveryTargets.filter(isDeliveryTarget)
+        : undefined;
+    const context = {};
+    if (sessionKey)
+        context.sessionKey = sessionKey;
+    if (messageChannel)
+        context.messageChannel = messageChannel;
+    if (requesterSenderId)
+        context.requesterSenderId = requesterSenderId;
+    if (agentAccountId)
+        context.agentAccountId = agentAccountId;
+    if (currentChat)
+        context.currentChat = currentChat;
+    if (deliveryTargets && deliveryTargets.length > 0)
+        context.deliveryTargets = deliveryTargets;
+    return Object.keys(context).length > 0 ? context : undefined;
+}
 function buildSentinelEventEnvelope(payload) {
     const watcherId = asString(payload.watcherId) ??
         getNestedString(payload, ["watcher", "id"]) ??
@@ -136,6 +174,7 @@ function buildSentinelEventEnvelope(payload) {
     const hookSessionGroup = asString(payload.hookSessionGroup) ??
         asString(payload.sessionGroup) ??
         getNestedString(payload, ["watcher", "sessionGroup"]);
+    const deliveryContext = extractDeliveryContext(payload);
     const envelope = {
         watcherId: watcherId ?? null,
         eventName: eventName ?? null,
@@ -154,6 +193,8 @@ function buildSentinelEventEnvelope(payload) {
         envelope.hookSessionGroup = hookSessionGroup;
     if (deliveryTargets && deliveryTargets.length > 0)
         envelope.deliveryTargets = deliveryTargets;
+    if (deliveryContext)
+        envelope.deliveryContext = deliveryContext;
     return envelope;
 }
 function buildSentinelSystemEvent(envelope) {
@@ -192,10 +233,30 @@ function inferTargetFromSessionKey(sessionKey, accountId) {
     };
 }
 function inferRelayTargets(payload, envelope) {
-    if (envelope.deliveryTargets?.length) {
-        return normalizeDeliveryTargets(envelope.deliveryTargets);
-    }
     const inferred = [];
+    if (envelope.deliveryTargets?.length)
+        inferred.push(...envelope.deliveryTargets);
+    if (envelope.deliveryContext?.deliveryTargets?.length) {
+        inferred.push(...envelope.deliveryContext.deliveryTargets);
+    }
+    if (envelope.deliveryContext?.currentChat)
+        inferred.push(envelope.deliveryContext.currentChat);
+    if (envelope.deliveryContext?.messageChannel && envelope.deliveryContext?.requesterSenderId) {
+        if (SUPPORTED_DELIVERY_CHANNELS.has(envelope.deliveryContext.messageChannel)) {
+            inferred.push({
+                channel: envelope.deliveryContext.messageChannel,
+                to: envelope.deliveryContext.requesterSenderId,
+                ...(envelope.deliveryContext.agentAccountId
+                    ? { accountId: envelope.deliveryContext.agentAccountId }
+                    : {}),
+            });
+        }
+    }
+    if (envelope.deliveryContext?.sessionKey) {
+        const target = inferTargetFromSessionKey(envelope.deliveryContext.sessionKey, envelope.deliveryContext.agentAccountId);
+        if (target)
+            inferred.push(target);
+    }
     if (isDeliveryTarget(payload.currentChat))
         inferred.push(payload.currentChat);
     const sourceCurrentChat = isRecord(payload.source) ? payload.source.currentChat : undefined;
@@ -245,7 +306,32 @@ function buildRelayMessage(envelope) {
     if (contextSummary)
         lines.push(contextSummary);
     const text = lines.join("\n").trim();
-    return text.length > 0 ? text : "Sentinel callback received.";
+    return text.length > 0
+        ? text
+        : "Sentinel callback received, but no assistant detail was generated.";
+}
+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);
+    if (parts.length === 0)
+        return undefined;
+    return trimText(parts.join("\n\n"), MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
+}
+function resolveHookResponseDedupeWindowMs(config) {
+    const candidate = config.hookResponseDedupeWindowMs ??
+        config.hookRelayDedupeWindowMs ??
+        DEFAULT_RELAY_DEDUPE_WINDOW_MS;
+    return Math.max(0, candidate);
+}
+function resolveHookResponseTimeoutMs(config) {
+    const candidate = config.hookResponseTimeoutMs ?? DEFAULT_HOOK_RESPONSE_TIMEOUT_MS;
+    return Math.max(0, candidate);
+}
+function resolveHookResponseFallbackMode(config) {
+    return config.hookResponseFallbackMode === "none" ? "none" : DEFAULT_HOOK_RESPONSE_FALLBACK_MODE;
 }
 function buildIsolatedHookSessionKey(envelope, config) {
     const rawPrefix = asString(config.hookSessionKey) ??
@@ -336,6 +422,166 @@ async function notifyDeliveryTarget(api, target, message) {
             throw new Error(`Unsupported delivery target channel: ${target.channel}`);
     }
 }
+async function deliverMessageToTargets(api, targets, message) {
+    if (targets.length === 0)
+        return { delivered: 0, failed: 0 };
+    const results = await Promise.all(targets.map(async (target) => {
+        try {
+            await notifyDeliveryTarget(api, target, message);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    const delivered = results.filter(Boolean).length;
+    return {
+        delivered,
+        failed: results.length - delivered,
+    };
+}
+class HookResponseRelayManager {
+    config;
+    api;
+    recentByDedupe = new Map();
+    pendingByDedupe = new Map();
+    pendingQueueBySession = new Map();
+    constructor(config, api) {
+        this.config = config;
+        this.api = api;
+    }
+    register(args) {
+        const dedupeWindowMs = resolveHookResponseDedupeWindowMs(this.config);
+        const now = Date.now();
+        if (dedupeWindowMs > 0) {
+            for (const [key, ts] of this.recentByDedupe.entries()) {
+                if (now - ts > dedupeWindowMs) {
+                    this.recentByDedupe.delete(key);
+                    this.pendingByDedupe.delete(key);
+                }
+            }
+        }
+        const existingTs = this.recentByDedupe.get(args.dedupeKey);
+        if (dedupeWindowMs > 0 &&
+            typeof existingTs === "number" &&
+            now - existingTs <= dedupeWindowMs) {
+            return {
+                dedupeKey: args.dedupeKey,
+                attempted: args.relayTargets.length,
+                delivered: 0,
+                failed: 0,
+                deduped: true,
+                pending: false,
+                timeoutMs: resolveHookResponseTimeoutMs(this.config),
+                fallbackMode: resolveHookResponseFallbackMode(this.config),
+            };
+        }
+        this.recentByDedupe.set(args.dedupeKey, now);
+        const timeoutMs = resolveHookResponseTimeoutMs(this.config);
+        const fallbackMode = resolveHookResponseFallbackMode(this.config);
+        if (args.relayTargets.length === 0) {
+            return {
+                dedupeKey: args.dedupeKey,
+                attempted: 0,
+                delivered: 0,
+                failed: 0,
+                deduped: false,
+                pending: false,
+                timeoutMs,
+                fallbackMode,
+            };
+        }
+        const pending = {
+            dedupeKey: args.dedupeKey,
+            sessionKey: args.sessionKey,
+            relayTargets: args.relayTargets,
+            fallbackMessage: args.fallbackMessage,
+            createdAt: now,
+            timeoutMs,
+            fallbackMode,
+            state: "pending",
+        };
+        this.pendingByDedupe.set(args.dedupeKey, pending);
+        const queue = this.pendingQueueBySession.get(args.sessionKey) ?? [];
+        queue.push(args.dedupeKey);
+        this.pendingQueueBySession.set(args.sessionKey, queue);
+        if (timeoutMs === 0) {
+            void this.handleTimeout(args.dedupeKey);
+        }
+        else {
+            pending.timer = setTimeout(() => {
+                void this.handleTimeout(args.dedupeKey);
+            }, timeoutMs);
+        }
+        return {
+            dedupeKey: args.dedupeKey,
+            attempted: args.relayTargets.length,
+            delivered: 0,
+            failed: 0,
+            deduped: false,
+            pending: true,
+            timeoutMs,
+            fallbackMode,
+        };
+    }
+    async handleLlmOutput(sessionKey, assistantTexts) {
+        if (!sessionKey)
+            return;
+        const assistantMessage = normalizeAssistantRelayText(assistantTexts);
+        if (!assistantMessage)
+            return;
+        const dedupeKey = this.popNextPendingDedupe(sessionKey);
+        if (!dedupeKey)
+            return;
+        const pending = this.pendingByDedupe.get(dedupeKey);
+        if (!pending || pending.state !== "pending")
+            return;
+        await this.completeWithMessage(pending, assistantMessage, "assistant");
+    }
+    popNextPendingDedupe(sessionKey) {
+        const queue = this.pendingQueueBySession.get(sessionKey);
+        if (!queue || queue.length === 0)
+            return undefined;
+        while (queue.length > 0) {
+            const next = queue.shift();
+            if (!next)
+                continue;
+            const pending = this.pendingByDedupe.get(next);
+            if (pending && pending.state === "pending") {
+                if (queue.length === 0)
+                    this.pendingQueueBySession.delete(sessionKey);
+                else
+                    this.pendingQueueBySession.set(sessionKey, queue);
+                return next;
+            }
+        }
+        this.pendingQueueBySession.delete(sessionKey);
+        return undefined;
+    }
+    async handleTimeout(dedupeKey) {
+        const pending = this.pendingByDedupe.get(dedupeKey);
+        if (!pending || pending.state !== "pending")
+            return;
+        if (pending.fallbackMode === "none") {
+            this.markClosed(pending, "timed_out");
+            return;
+        }
+        await this.completeWithMessage(pending, pending.fallbackMessage, "timeout");
+    }
+    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}`);
+    }
+    markClosed(pending, state) {
+        pending.state = state;
+        if (pending.timer) {
+            clearTimeout(pending.timer);
+            pending.timer = undefined;
+        }
+        this.pendingByDedupe.set(pending.dedupeKey, pending);
+    }
+}
 export function createSentinelPlugin(overrides) {
     const config = {
         allowedHosts: [],
@@ -343,6 +589,9 @@ export function createSentinelPlugin(overrides) {
         dispatchAuthToken: process.env.SENTINEL_DISPATCH_TOKEN,
         hookSessionPrefix: DEFAULT_HOOK_SESSION_PREFIX,
         hookRelayDedupeWindowMs: DEFAULT_RELAY_DEDUPE_WINDOW_MS,
+        hookResponseTimeoutMs: DEFAULT_HOOK_RESPONSE_TIMEOUT_MS,
+        hookResponseFallbackMode: DEFAULT_HOOK_RESPONSE_FALLBACK_MODE,
+        hookResponseDedupeWindowMs: DEFAULT_RELAY_DEDUPE_WINDOW_MS,
         notificationPayloadMode: "concise",
         limits: {
             maxWatchersTotal: 200,
@@ -352,22 +601,6 @@ 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" };
@@ -389,6 +622,12 @@ export function createSentinelPlugin(overrides) {
             const runtimeConfig = resolveSentinelPluginConfig(api);
             if (Object.keys(runtimeConfig).length > 0)
                 Object.assign(config, runtimeConfig);
+            const hookResponseRelayManager = new HookResponseRelayManager(config, api);
+            if (typeof api.on === "function") {
+                api.on("llm_output", (event, ctx) => {
+                    void hookResponseRelayManager.handleLlmOutput(ctx?.sessionKey, event.assistantTexts);
+                });
+            }
             manager.setNotifier({
                 async notify(target, message) {
                     await notifyDeliveryTarget(api, target, message);
@@ -426,36 +665,21 @@ export function createSentinelPlugin(overrides) {
                             const envelope = buildSentinelEventEnvelope(payload);
                             const sessionKey = buildIsolatedHookSessionKey(envelope, config);
                             const text = buildSentinelSystemEvent(envelope);
-                            const enqueued = api.runtime.system.enqueueSystemEvent(text, { sessionKey });
+                            const enqueued = api.runtime.system.enqueueSystemEvent(text, {
+                                sessionKey,
+                                contextKey: SENTINEL_CALLBACK_CONTEXT_KEY,
+                            });
                             api.runtime.system.requestHeartbeatNow({
-                                reason: "hook:sentinel",
+                                reason: SENTINEL_CALLBACK_WAKE_REASON,
                                 sessionKey,
                             });
                             const relayTargets = inferRelayTargets(payload, envelope);
-                            const relayMessage = buildRelayMessage(envelope);
-                            const relay = {
+                            const relay = hookResponseRelayManager.register({
                                 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;
-                                        }
-                                    }));
-                                }
-                            }
+                                sessionKey,
+                                relayTargets,
+                                fallbackMessage: buildRelayMessage(envelope),
+                            });
                             res.writeHead(200, { "content-type": "application/json" });
                             res.end(JSON.stringify({
                                 ok: true,

package/dist/tool.js

@@ -1,5 +1,6 @@
 import { jsonResult } from "openclaw/plugin-sdk";
 import { Value } from "@sinclair/typebox/value";
+import { SENTINEL_ORIGIN_ACCOUNT_METADATA, SENTINEL_ORIGIN_CHANNEL_METADATA, SENTINEL_ORIGIN_SESSION_KEY_METADATA, SENTINEL_ORIGIN_TARGET_METADATA, } from "./types.js";
 import { SentinelToolSchema, SentinelToolValidationSchema } from "./toolSchema.js";
 import { TemplateValueSchema } from "./templateValueSchema.js";
 function validateParams(params) {
@@ -63,6 +64,30 @@ function inferDefaultDeliveryTargets(ctx) {
     }
     return [];
 }
+function maybeSetMetadata(metadata, key, value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return;
+    if (!metadata[key])
+        metadata[key] = trimmed;
+}
+function addOriginDeliveryMetadata(watcher, ctx) {
+    const metadataRaw = watcher.metadata;
+    const metadata = metadataRaw && typeof metadataRaw === "object" && !Array.isArray(metadataRaw)
+        ? { ...metadataRaw }
+        : {};
+    const sessionPeer = ctx.sessionKey?.split(":").at(-1)?.trim();
+    maybeSetMetadata(metadata, SENTINEL_ORIGIN_SESSION_KEY_METADATA, ctx.sessionKey);
+    maybeSetMetadata(metadata, SENTINEL_ORIGIN_CHANNEL_METADATA, ctx.messageChannel);
+    maybeSetMetadata(metadata, SENTINEL_ORIGIN_TARGET_METADATA, ctx.requesterSenderId ?? sessionPeer);
+    maybeSetMetadata(metadata, SENTINEL_ORIGIN_ACCOUNT_METADATA, ctx.agentAccountId);
+    if (Object.keys(metadata).length === 0)
+        return watcher;
+    return {
+        ...watcher,
+        metadata,
+    };
+}
 export function registerSentinelControl(registerTool, manager) {
     registerTool((ctx) => ({
         name: "sentinel_control",
@@ -73,10 +98,12 @@ export function registerSentinelControl(registerTool, manager) {
             const payload = validateParams(params);
             switch (payload.action) {
                 case "create":
-                case "add":
-                    return normalizeToolResultText(await manager.create(payload.watcher, {
+                case "add": {
+                    const watcherWithContext = addOriginDeliveryMetadata(payload.watcher, ctx);
+                    return normalizeToolResultText(await manager.create(watcherWithContext, {
                         deliveryTargets: inferDefaultDeliveryTargets(ctx),
                     }), "Watcher created");
+                }
                 case "enable":
                     await manager.enable(payload.id);
                     return normalizeToolResultText(undefined, `Enabled watcher: ${payload.id}`);

package/dist/types.d.ts

@@ -9,6 +9,11 @@ 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 type HookResponseFallbackMode = "none" | "concise";
+export declare const SENTINEL_ORIGIN_SESSION_KEY_METADATA = "openclaw.sentinel.origin.sessionKey";
+export declare const SENTINEL_ORIGIN_CHANNEL_METADATA = "openclaw.sentinel.origin.channel";
+export declare const SENTINEL_ORIGIN_TARGET_METADATA = "openclaw.sentinel.origin.to";
+export declare const SENTINEL_ORIGIN_ACCOUNT_METADATA = "openclaw.sentinel.origin.accountId";
 export interface FireConfig {
     webhookPath?: string;
     eventName: string;
@@ -92,6 +97,9 @@ export interface SentinelConfig {
     hookSessionPrefix?: string;
     hookSessionGroup?: string;
     hookRelayDedupeWindowMs?: number;
+    hookResponseTimeoutMs?: number;
+    hookResponseFallbackMode?: HookResponseFallbackMode;
+    hookResponseDedupeWindowMs?: number;
     stateFilePath?: string;
     notificationPayloadMode?: NotificationPayloadMode;
     limits: SentinelLimits;

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/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": []
       },
@@ -74,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
       }
     }
   },
@@ -141,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.5",
+  "version": "0.5.1",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",