@coffeexdev/openclaw-sentinel 0.4.4 → 0.5.0

package/dist/index.js

@@ -1,14 +1,26 @@
 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_KEY = "agent:main:main";
+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_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 +40,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 +68,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 +91,63 @@ 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 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) ??
-        (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 +161,17 @@ 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 deliveryContext = extractDeliveryContext(payload);
     const envelope = {
         watcherId: watcherId ?? null,
         eventName: eventName ?? null,
@@ -90,22 +180,169 @@ 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;
+    if (deliveryContext)
+        envelope.deliveryContext = deliveryContext;
     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) {
+    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;
+    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 normalizeAssistantRelayText(assistantTexts) {
+    if (!Array.isArray(assistantTexts) || assistantTexts.length === 0)
+        return undefined;
+    const parts = assistantTexts.map((value) => value.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) ??
+        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))
@@ -178,12 +415,177 @@ 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: [],
         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,
+        hookResponseTimeoutMs: DEFAULT_HOOK_RESPONSE_TIMEOUT_MS,
+        hookResponseFallbackMode: DEFAULT_HOOK_RESPONSE_FALLBACK_MODE,
+        hookResponseDedupeWindowMs: DEFAULT_RELAY_DEDUPE_WINDOW_MS,
+        notificationPayloadMode: "concise",
         limits: {
             maxWatchersTotal: 200,
             maxWatchersPerSkill: 20,
@@ -210,6 +612,15 @@ export function createSentinelPlugin(overrides) {
             await manager.init();
         },
         register(api) {
+            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);
@@ -244,19 +655,28 @@ 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 relay = hookResponseRelayManager.register({
+                                dedupeKey: envelope.dedupeKey,
+                                sessionKey,
+                                relayTargets,
+                                fallbackMessage: buildRelayMessage(envelope),
+                            });
                             res.writeHead(200, { "content-type": "application/json" });
                             res.end(JSON.stringify({
                                 ok: true,
                                 route: path,
                                 sessionKey,
                                 enqueued,
+                                relay,
                             }));
                         }
                         catch (err) {

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/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,13 @@ 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 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;
@@ -16,6 +23,8 @@ export interface FireConfig {
     priority?: PriorityLevel;
     deadlineTemplate?: string;
     dedupeKeyTemplate?: string;
+    notificationPayloadMode?: NotificationPayloadModeOverride;
+    sessionGroup?: string;
 }
 export interface RetryPolicy {
     maxRetries: number;
@@ -83,8 +92,16 @@ export interface SentinelConfig {
     allowedHosts: string[];
     localDispatchBase: string;
     dispatchAuthToken?: string;
+    /** @deprecated Backward-compatible alias for hookSessionPrefix. */
     hookSessionKey?: string;
+    hookSessionPrefix?: string;
+    hookSessionGroup?: string;
+    hookRelayDedupeWindowMs?: number;
+    hookResponseTimeoutMs?: number;
+    hookResponseFallbackMode?: HookResponseFallbackMode;
+    hookResponseDedupeWindowMs?: number;
     stateFilePath?: string;
+    notificationPayloadMode?: NotificationPayloadMode;
     limits: SentinelLimits;
 }
 export interface GatewayWebhookDispatcher {