@coffeexdev/openclaw-sentinel 0.2.1 → 0.4.0

package/README.md

@@ -58,6 +58,14 @@ openclaw gateway restart
     "fire": {
       "webhookPath": "/hooks/sentinel",
       "eventName": "eth_target_hit",
+      "intent": "price_threshold_review",
+      "contextTemplate": {
+        "asset": "ETH",
+        "priceUsd": "${payload.ethereum.usd}",
+        "workflow": "alerts"
+      },
+      "priority": "high",
+      "deadlineTemplate": "${timestamp}",
       "payloadTemplate": {
         "event": "${event.name}",
         "price": "${payload.ethereum.usd}",
@@ -87,12 +95,35 @@ Use `sentinel_control`:
 ## What happens when a watcher fires?
 
 1. Sentinel evaluates conditions.
-2. On match, it dispatches to `localDispatchBase + webhookPath`.
-3. For `/hooks/sentinel`, the plugin route enqueues a system event and requests heartbeat wake.
-4. OpenClaw wakes and processes that event in the configured session (`hookSessionKey`, default `agent:main:main`).
+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`).
 
 The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent).
 
+Sample emitted envelope:
+
+```json
+{
+  "type": "sentinel.callback",
+  "version": "1",
+  "intent": "price_threshold_review",
+  "actionable": true,
+  "watcher": { "id": "eth-price-watch", "skillId": "skills.alerts", "eventName": "eth_target_hit" },
+  "trigger": {
+    "matchedAt": "2026-03-04T15:00:00.000Z",
+    "dedupeKey": "<sha256>",
+    "priority": "high"
+  },
+  "context": { "asset": "ETH", "priceUsd": 5001, "workflow": "alerts" },
+  "payload": { "ethereum": { "usd": 5001 } },
+  "deliveryTargets": [{ "channel": "telegram", "to": "5613673222" }],
+  "source": { "plugin": "openclaw-sentinel", "route": "/hooks/sentinel" }
+}
+```
+
 ## Why Sentinel
 
 Sentinel runs watcher lifecycles inside the gateway with fixed strategies and declarative conditions.
@@ -143,11 +174,17 @@ It **does not** execute user-authored code from watcher definitions.
         "ts": "${timestamp}"
       }
     },
-    "retry": { "maxRetries": 5, "baseMs": 250, "maxMs": 5000 }
+    "retry": { "maxRetries": 5, "baseMs": 250, "maxMs": 5000 },
+    "deliveryTargets": [
+      { "channel": "telegram", "to": "5613673222" },
+      { "channel": "discord", "to": "123456789012345678", "accountId": "main" }
+    ]
   }
 }
 ```
 
+`deliveryTargets` is optional. If omitted on `create`, Sentinel infers a default target from the current tool/session context (channel + current peer).
+
 ## Runtime controls
 
 ```json
@@ -185,10 +222,10 @@ openclaw-sentinel audit
 ## Development
 
 ```bash
-npm i
-npm run lint
-npm run test
-npm run build
+pnpm install
+pnpm run lint
+pnpm test
+pnpm run build
 ```
 
 ## License

package/dist/callbackEnvelope.d.ts

@@ -0,0 +1,8 @@
+import { WatcherDefinition } from "./types.js";
+export declare function createCallbackEnvelope(args: {
+    watcher: WatcherDefinition;
+    payload: unknown;
+    payloadBody: Record<string, unknown>;
+    matchedAt: string;
+    webhookPath: string;
+}): Record<string, unknown>;

package/dist/callbackEnvelope.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { renderTemplate } from "./template.js";
+const MAX_PAYLOAD_JSON_CHARS = 4000;
+function toIntent(eventName) {
+    return (eventName
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, "_") || "sentinel_event");
+}
+function summarizePayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return { summary: String(payload) };
+    }
+    const obj = payload;
+    const out = {};
+    for (const key of Object.keys(obj).slice(0, 12))
+        out[key] = obj[key];
+    return out;
+}
+function truncatePayload(payload) {
+    const serialized = JSON.stringify(payload);
+    if (!serialized)
+        return payload;
+    if (serialized.length <= MAX_PAYLOAD_JSON_CHARS)
+        return payload;
+    return {
+        truncated: true,
+        maxChars: MAX_PAYLOAD_JSON_CHARS,
+        preview: serialized.slice(0, MAX_PAYLOAD_JSON_CHARS),
+    };
+}
+function getPath(obj, path) {
+    return path.split(".").reduce((acc, part) => acc?.[part], obj);
+}
+function getTemplateString(value, context) {
+    if (!value)
+        return undefined;
+    if (!value.includes("${"))
+        return value;
+    if (/^\$\{[^}]+\}$/.test(value)) {
+        const rendered = renderTemplate({ value }, context);
+        const resolved = rendered.value;
+        if (resolved === undefined || resolved === null)
+            return undefined;
+        return String(resolved);
+    }
+    return value.replaceAll(/\$\{([^}]+)\}/g, (_full, path) => {
+        if (!/^(watcher\.(id|skillId)|event\.(name)|payload\.[a-zA-Z0-9_.-]+|timestamp)$/.test(path)) {
+            throw new Error(`Template placeholder not allowed: $\{${path}\}`);
+        }
+        const resolved = getPath(context, path);
+        if (resolved === undefined || resolved === null) {
+            throw new Error(`Template placeholder unresolved: $\{${path}\}`);
+        }
+        return String(resolved);
+    });
+}
+export function createCallbackEnvelope(args) {
+    const { watcher, payload, payloadBody, matchedAt, webhookPath } = args;
+    const context = {
+        watcher,
+        event: { name: watcher.fire.eventName },
+        payload,
+        timestamp: matchedAt,
+    };
+    const intent = watcher.fire.intent ?? toIntent(watcher.fire.eventName);
+    const renderedContext = watcher.fire.contextTemplate
+        ? renderTemplate(watcher.fire.contextTemplate, context)
+        : payloadBody;
+    const priority = watcher.fire.priority ?? "normal";
+    const deadline = getTemplateString(watcher.fire.deadlineTemplate, context);
+    const dedupeSeed = getTemplateString(watcher.fire.dedupeKeyTemplate, context) ??
+        `${watcher.id}|${watcher.fire.eventName}|${matchedAt}`;
+    const dedupeKey = createHash("sha256").update(dedupeSeed).digest("hex");
+    return {
+        type: "sentinel.callback",
+        version: "1",
+        intent,
+        actionable: true,
+        watcher: {
+            id: watcher.id,
+            skillId: watcher.skillId,
+            eventName: watcher.fire.eventName,
+        },
+        trigger: {
+            matchedAt,
+            dedupeKey,
+            priority,
+            ...(deadline ? { deadline } : {}),
+        },
+        context: renderedContext ?? summarizePayload(payload),
+        payload: truncatePayload(payload),
+        deliveryTargets: watcher.deliveryTargets ?? [],
+        source: {
+            plugin: "openclaw-sentinel",
+            route: webhookPath,
+        },
+    };
+}

package/dist/configSchema.js

@@ -87,7 +87,6 @@ export const sentinelConfigSchema = {
             },
             localDispatchBase: {
                 type: "string",
-                format: "uri",
                 description: "Base URL for internal webhook dispatch",
                 default: "http://127.0.0.1:18789",
             },

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { sentinelConfigSchema } from "./configSchema.js";
 import { registerSentinelControl } from "./tool.js";
 import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
@@ -5,14 +6,9 @@ import { WatcherManager } from "./watcherManager.js";
 const registeredWebhookPathsByRegistrar = new WeakMap();
 const DEFAULT_HOOK_SESSION_KEY = "agent:main:main";
 const MAX_SENTINEL_WEBHOOK_BODY_BYTES = 64 * 1024;
-const MAX_SENTINEL_WEBHOOK_TEXT_CHARS = 2000;
-function normalizePath(path) {
-    const trimmed = path.trim();
-    if (!trimmed)
-        return DEFAULT_SENTINEL_WEBHOOK_PATH;
-    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-    return withSlash.length > 1 && withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
-}
+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.";
 function trimText(value, max) {
     return value.length <= max ? value : `${value.slice(0, max)}…`;
 }
@@ -22,22 +18,93 @@ function asString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function asIsoString(value) {
+    const text = asString(value);
+    if (!text)
+        return undefined;
+    const timestamp = Date.parse(text);
+    return Number.isNaN(timestamp) ? undefined : new Date(timestamp).toISOString();
+}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function buildSentinelSystemEvent(payload) {
-    const text = asString(payload.text) ?? asString(payload.message);
-    if (text)
-        return trimText(text, MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
-    const watcherId = asString(payload.watcherId);
+function isDeliveryTarget(value) {
+    return (isRecord(value) &&
+        typeof value.channel === "string" &&
+        typeof value.to === "string" &&
+        (value.accountId === undefined || typeof value.accountId === "string"));
+}
+function normalizePath(path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return DEFAULT_SENTINEL_WEBHOOK_PATH;
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return withSlash.length > 1 && withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+}
+function clipPayloadForPrompt(value) {
+    const serialized = JSON.stringify(value);
+    if (!serialized)
+        return value;
+    if (serialized.length <= MAX_SENTINEL_PAYLOAD_JSON_CHARS)
+        return value;
+    const clipped = serialized.slice(0, MAX_SENTINEL_PAYLOAD_JSON_CHARS);
+    const overflow = serialized.length - clipped.length;
+    return {
+        __truncated: true,
+        truncatedChars: overflow,
+        maxChars: MAX_SENTINEL_PAYLOAD_JSON_CHARS,
+        preview: `${clipped}…`,
+    };
+}
+function buildSentinelEventEnvelope(payload) {
+    const watcherId = asString(payload.watcherId) ??
+        (isRecord(payload.watcher) ? asString(payload.watcher.id) : undefined);
     const eventName = asString(payload.eventName) ??
         (isRecord(payload.event) ? asString(payload.event.name) : undefined);
-    const labels = ["Sentinel webhook received"];
-    if (eventName)
-        labels.push(`event=${eventName}`);
-    if (watcherId)
-        labels.push(`watcher=${watcherId}`);
-    return trimText(labels.join(" "), MAX_SENTINEL_WEBHOOK_TEXT_CHARS);
+    const skillId = asString(payload.skillId) ??
+        (isRecord(payload.watcher) ? asString(payload.watcher.skillId) : undefined) ??
+        undefined;
+    const matchedAt = asIsoString(payload.matchedAt) ?? asIsoString(payload.timestamp) ?? 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,
+        matchedAt,
+    });
+    const generatedDedupe = createHash("sha256").update(dedupeSeed).digest("hex").slice(0, 16);
+    const dedupeKey = asString(payload.dedupeKey) ??
+        asString(payload.correlationId) ??
+        asString(payload.correlationID) ??
+        generatedDedupe;
+    const deliveryTargets = Array.isArray(payload.deliveryTargets)
+        ? payload.deliveryTargets.filter(isDeliveryTarget)
+        : undefined;
+    const envelope = {
+        watcherId: watcherId ?? null,
+        eventName: eventName ?? null,
+        matchedAt,
+        payload: boundedPayload,
+        dedupeKey,
+        correlationId: dedupeKey,
+        source: {
+            route: DEFAULT_SENTINEL_WEBHOOK_PATH,
+            plugin: "openclaw-sentinel",
+        },
+    };
+    if (skillId)
+        envelope.skillId = skillId;
+    if (deliveryTargets && deliveryTargets.length > 0)
+        envelope.deliveryTargets = deliveryTargets;
+    return envelope;
+}
+function buildSentinelSystemEvent(payload) {
+    const envelope = buildSentinelEventEnvelope(payload);
+    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);
 }
 async function readSentinelWebhookPayload(req) {
     const preParsed = req.body;
@@ -70,6 +137,47 @@ async function readSentinelWebhookPayload(req) {
     }
     return parsed;
 }
+async function notifyDeliveryTarget(api, target, message) {
+    switch (target.channel) {
+        case "telegram":
+            await api.runtime.channel.telegram.sendMessageTelegram(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "discord":
+            await api.runtime.channel.discord.sendMessageDiscord(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "slack":
+            await api.runtime.channel.slack.sendMessageSlack(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "signal":
+            await api.runtime.channel.signal.sendMessageSignal(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "imessage":
+            await api.runtime.channel.imessage.sendMessageIMessage(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "whatsapp":
+            await api.runtime.channel.whatsapp.sendMessageWhatsApp(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        case "line":
+            await api.runtime.channel.line.sendMessageLine(target.to, message, {
+                accountId: target.accountId,
+            });
+            return;
+        default:
+            throw new Error(`Unsupported delivery target channel: ${target.channel}`);
+    }
+}
 export function createSentinelPlugin(overrides) {
     const config = {
         allowedHosts: [],
@@ -102,6 +210,11 @@ export function createSentinelPlugin(overrides) {
             await manager.init();
         },
         register(api) {
+            manager.setNotifier({
+                async notify(target, message) {
+                    await notifyDeliveryTarget(api, target, message);
+                },
+            });
             registerSentinelControl(api.registerTool.bind(api), manager);
             const path = normalizePath(DEFAULT_SENTINEL_WEBHOOK_PATH);
             if (!api.registerHttpRoute) {

package/dist/strategies/base.d.ts

@@ -1,2 +1,5 @@
 import { WatcherDefinition } from "../types.js";
-export type StrategyHandler = (watcher: WatcherDefinition, onPayload: (payload: unknown) => Promise<void>, onError: (error: unknown) => Promise<void>) => Promise<() => void>;
+export interface StrategyCallbacks {
+    onConnect?: () => void;
+}
+export type StrategyHandler = (watcher: WatcherDefinition, onPayload: (payload: unknown) => Promise<void>, onError: (error: unknown) => Promise<void>, callbacks?: StrategyCallbacks) => Promise<() => void>;

package/dist/strategies/websocket.js

@@ -1,9 +1,16 @@
 import WebSocket from "ws";
-export const websocketStrategy = async (watcher, onPayload, onError) => {
+export const websocketStrategy = async (watcher, onPayload, onError, callbacks) => {
     let active = true;
     let ws = null;
     const connect = () => {
+        let pendingError = null;
+        let failureReported = false;
         ws = new WebSocket(watcher.endpoint, { headers: watcher.headers });
+        ws.on("open", () => {
+            if (!active)
+                return;
+            callbacks?.onConnect?.();
+        });
         ws.on("message", async (data) => {
             if (!active)
                 return;
@@ -18,12 +25,14 @@ export const websocketStrategy = async (watcher, onPayload, onError) => {
         ws.on("error", (err) => {
             if (!active)
                 return;
-            void onError(err);
+            pendingError = err instanceof Error ? err : new Error(String(err));
         });
         ws.on("close", (code) => {
-            if (!active)
+            if (!active || failureReported)
                 return;
-            void onError(new Error(`websocket closed: ${code}`));
+            failureReported = true;
+            const reason = pendingError?.message ?? `websocket closed: ${code}`;
+            void onError(new Error(reason));
         });
     };
     connect();

package/dist/template.d.ts

@@ -1 +1,4 @@
-export declare function renderTemplate(template: Record<string, string | number | boolean | null>, context: Record<string, unknown>): Record<string, unknown>;
+export type TemplateValue = string | number | boolean | null | {
+    [key: string]: TemplateValue;
+} | TemplateValue[];
+export declare function renderTemplate(template: Record<string, TemplateValue>, context: Record<string, unknown>): Record<string, unknown>;

package/dist/template.js

@@ -2,17 +2,12 @@ const placeholderPattern = /^\$\{(watcher\.(id|skillId)|event\.(name)|payload\.[
 function getPath(obj, path) {
     return path.split(".").reduce((acc, part) => acc?.[part], obj);
 }
-export function renderTemplate(template, context) {
-    const out = {};
-    for (const [key, value] of Object.entries(template)) {
-        if (typeof value !== "string") {
-            out[key] = value;
-            continue;
-        }
-        if (!value.startsWith("${")) {
-            out[key] = value;
-            continue;
-        }
+function renderValue(value, context) {
+    if (value === null || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        if (!value.startsWith("${"))
+            return value;
         if (!placeholderPattern.test(value)) {
             throw new Error(`Template placeholder not allowed: ${value}`);
         }
@@ -20,7 +15,16 @@ export function renderTemplate(template, context) {
         const resolved = getPath(context, path);
         if (resolved === undefined)
             throw new Error(`Template placeholder unresolved: ${value}`);
-        out[key] = resolved;
+        return resolved;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => renderValue(item, context));
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = renderValue(child, context);
     }
     return out;
 }
+export function renderTemplate(template, context) {
+    return renderValue(template, context);
+}

package/dist/tool.d.ts

@@ -3,6 +3,12 @@ import type { Static } from "@sinclair/typebox";
 import { WatcherManager } from "./watcherManager.js";
 import { SentinelToolSchema } from "./toolSchema.js";
 export type SentinelToolParams = Static<typeof SentinelToolSchema>;
-type RegisterToolFn = (tool: AnyAgentTool) => void;
+type SentinelToolContext = {
+    messageChannel?: string;
+    requesterSenderId?: string;
+    agentAccountId?: string;
+    sessionKey?: string;
+};
+type RegisterToolFn = (tool: AnyAgentTool | ((ctx: SentinelToolContext) => AnyAgentTool)) => void;
 export declare function registerSentinelControl(registerTool: RegisterToolFn, manager: WatcherManager): void;
 export {};

package/dist/tool.js

@@ -11,8 +11,22 @@ function validateParams(params) {
     }
     return candidate;
 }
+function inferDefaultDeliveryTargets(ctx) {
+    const channel = ctx.messageChannel?.trim();
+    if (!channel)
+        return [];
+    const fromSender = ctx.requesterSenderId?.trim();
+    if (fromSender) {
+        return [{ channel, to: fromSender, accountId: ctx.agentAccountId }];
+    }
+    const sessionPeer = ctx.sessionKey?.split(":").at(-1)?.trim();
+    if (sessionPeer) {
+        return [{ channel, to: sessionPeer, accountId: ctx.agentAccountId }];
+    }
+    return [];
+}
 export function registerSentinelControl(registerTool, manager) {
-    registerTool({
+    registerTool((ctx) => ({
         name: "sentinel_control",
         label: "sentinel_control",
         description: "Create/manage sentinel watchers",
@@ -21,7 +35,9 @@ export function registerSentinelControl(registerTool, manager) {
             const payload = validateParams(params);
             switch (payload.action) {
                 case "create":
-                    return jsonResult(await manager.create(payload.watcher));
+                    return jsonResult(await manager.create(payload.watcher, {
+                        deliveryTargets: inferDefaultDeliveryTargets(ctx),
+                    }));
                 case "enable":
                     return jsonResult(await manager.enable(payload.id ?? ""));
                 case "disable":
@@ -34,5 +50,5 @@ export function registerSentinelControl(registerTool, manager) {
                     return jsonResult(manager.list());
             }
         },
-    });
+    }));
 }

package/dist/toolSchema.d.ts

@@ -21,7 +21,12 @@ export declare const SentinelToolSchema: import("@sinclair/typebox").TObject<{
         fire: import("@sinclair/typebox").TObject<{
             webhookPath: import("@sinclair/typebox").TString;
             eventName: import("@sinclair/typebox").TString;
-            payloadTemplate: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TString, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNull]>>;
+            payloadTemplate: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, any>;
+            intent: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            contextTemplate: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, any>>;
+            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>;
         }>;
         retry: import("@sinclair/typebox").TObject<{
             maxRetries: import("@sinclair/typebox").TNumber;
@@ -29,6 +34,11 @@ export declare const SentinelToolSchema: import("@sinclair/typebox").TObject<{
             maxMs: import("@sinclair/typebox").TNumber;
         }>;
         fireOnce: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        deliveryTargets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            channel: import("@sinclair/typebox").TString;
+            to: import("@sinclair/typebox").TString;
+            accountId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>>;
         metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
     }>>;
 }>;

package/dist/toolSchema.js

@@ -1,4 +1,12 @@
 import { Type } from "@sinclair/typebox";
+const TemplateValueSchema = Type.Recursive((Self) => Type.Union([
+    Type.String(),
+    Type.Number(),
+    Type.Boolean(),
+    Type.Null(),
+    Type.Array(Self),
+    Type.Record(Type.String(), Self),
+]));
 const ConditionSchema = Type.Object({
     path: Type.String({ description: "JSONPath expression to evaluate against the response" }),
     op: Type.Union([
@@ -23,15 +31,27 @@ const FireConfigSchema = Type.Object({
         description: "Path appended to localDispatchBase for webhook delivery",
     }),
     eventName: Type.String({ description: "Event name included in the dispatched payload" }),
-    payloadTemplate: Type.Record(Type.String(), Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()]), {
+    payloadTemplate: Type.Record(Type.String(), TemplateValueSchema, {
         description: "Key-value template for the webhook payload. Supports ${...} interpolation from matched response data.",
     }),
+    intent: Type.Optional(Type.String({ description: "Generic callback intent for downstream agent routing" })),
+    contextTemplate: Type.Optional(Type.Record(Type.String(), TemplateValueSchema, {
+        description: "Structured callback context template. Supports ${...} interpolation from matched response data.",
+    })),
+    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" })),
 });
 const RetryPolicySchema = Type.Object({
     maxRetries: Type.Number({ description: "Maximum number of retry attempts" }),
     baseMs: Type.Number({ description: "Base delay in milliseconds for exponential backoff" }),
     maxMs: Type.Number({ description: "Maximum delay cap in milliseconds" }),
 });
+const DeliveryTargetSchema = Type.Object({
+    channel: Type.String({ description: "Channel/provider id (e.g. telegram, discord)" }),
+    to: Type.String({ description: "Destination id within the channel" }),
+    accountId: Type.Optional(Type.String({ description: "Optional account id for multi-account channels" })),
+}, { additionalProperties: false });
 const WatcherSchema = Type.Object({
     id: Type.String({ description: "Unique watcher identifier" }),
     skillId: Type.String({ description: "ID of the skill that owns this watcher" }),
@@ -61,6 +81,9 @@ const WatcherSchema = Type.Object({
     fire: FireConfigSchema,
     retry: RetryPolicySchema,
     fireOnce: Type.Optional(Type.Boolean({ description: "If true, the watcher disables itself after firing once" })),
+    deliveryTargets: Type.Optional(Type.Array(DeliveryTargetSchema, {
+        description: "Optional notification delivery targets. Defaults to the current chat/session context when omitted.",
+    })),
     metadata: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Arbitrary key-value metadata" })),
 }, { description: "Full watcher definition" });
 export const SentinelToolSchema = Type.Object({

package/dist/types.d.ts

@@ -6,16 +6,27 @@ export interface Condition {
     value?: unknown;
 }
 export declare const DEFAULT_SENTINEL_WEBHOOK_PATH = "/hooks/sentinel";
+export type PriorityLevel = "low" | "normal" | "high" | "critical";
 export interface FireConfig {
     webhookPath?: string;
     eventName: string;
-    payloadTemplate: Record<string, string | number | boolean | null>;
+    payloadTemplate: Record<string, import("./template.js").TemplateValue>;
+    intent?: string;
+    contextTemplate?: Record<string, import("./template.js").TemplateValue>;
+    priority?: PriorityLevel;
+    deadlineTemplate?: string;
+    dedupeKeyTemplate?: string;
 }
 export interface RetryPolicy {
     maxRetries: number;
     baseMs: number;
     maxMs: number;
 }
+export interface DeliveryTarget {
+    channel: string;
+    to: string;
+    accountId?: string;
+}
 export interface WatcherDefinition {
     id: string;
     skillId: string;
@@ -32,6 +43,7 @@ export interface WatcherDefinition {
     fire: FireConfig;
     retry: RetryPolicy;
     fireOnce?: boolean;
+    deliveryTargets?: DeliveryTarget[];
     metadata?: Record<string, string>;
 }
 export interface WatcherRuntimeState {
@@ -39,9 +51,22 @@ export interface WatcherRuntimeState {
     lastError?: string;
     lastResponseAt?: string;
     consecutiveFailures: number;
+    reconnectAttempts: number;
     lastPayloadHash?: string;
     lastPayload?: unknown;
     lastEvaluated?: string;
+    lastConnectAt?: string;
+    lastDisconnectAt?: string;
+    lastDisconnectReason?: string;
+    lastDelivery?: {
+        attemptedAt: string;
+        successCount: number;
+        failureCount: number;
+        failures?: Array<{
+            target: DeliveryTarget;
+            error: string;
+        }>;
+    };
 }
 export interface SentinelStateFile {
     watchers: WatcherDefinition[];

package/dist/validator.js

@@ -3,6 +3,14 @@ import { Value } from "@sinclair/typebox/value";
 import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
 const codeyKeyPattern = /(script|code|eval|handler|function|import|require)/i;
 const codeyValuePattern = /(=>|\bfunction\b|\bimport\s+|\brequire\s*\(|\beval\s*\()/i;
+const TemplateValueSchema = Type.Recursive((Self) => Type.Union([
+    Type.String(),
+    Type.Number(),
+    Type.Boolean(),
+    Type.Null(),
+    Type.Array(Self),
+    Type.Record(Type.String(), Self),
+]));
 const ConditionSchema = Type.Object({
     path: Type.String({ minLength: 1 }),
     op: Type.Union([
@@ -41,7 +49,17 @@ const WatcherSchema = Type.Object({
     fire: Type.Object({
         webhookPath: Type.Optional(Type.String({ pattern: "^/" })),
         eventName: Type.String({ minLength: 1 }),
-        payloadTemplate: Type.Record(Type.String(), Type.Union([Type.String(), Type.Number(), Type.Boolean(), Type.Null()])),
+        payloadTemplate: Type.Record(Type.String(), TemplateValueSchema),
+        intent: Type.Optional(Type.String({ minLength: 1 })),
+        contextTemplate: Type.Optional(Type.Record(Type.String(), TemplateValueSchema)),
+        priority: Type.Optional(Type.Union([
+            Type.Literal("low"),
+            Type.Literal("normal"),
+            Type.Literal("high"),
+            Type.Literal("critical"),
+        ])),
+        deadlineTemplate: Type.Optional(Type.String({ minLength: 1 })),
+        dedupeKeyTemplate: Type.Optional(Type.String({ minLength: 1 })),
     }, { additionalProperties: false }),
     retry: Type.Object({
         maxRetries: Type.Integer({ minimum: 0, maximum: 20 }),
@@ -49,6 +67,11 @@ const WatcherSchema = Type.Object({
         maxMs: Type.Integer({ minimum: 100, maximum: 300000 }),
     }, { additionalProperties: false }),
     fireOnce: Type.Optional(Type.Boolean()),
+    deliveryTargets: Type.Optional(Type.Array(Type.Object({
+        channel: Type.String({ minLength: 1 }),
+        to: Type.String({ minLength: 1 }),
+        accountId: Type.Optional(Type.String({ minLength: 1 })),
+    }, { additionalProperties: false }), { minItems: 1 })),
     metadata: Type.Optional(Type.Record(Type.String(), Type.String())),
 }, { additionalProperties: false });
 function scanNoCodeLike(input, parentKey = "") {

package/dist/watcherManager.d.ts

@@ -1,18 +1,28 @@
-import { GatewayWebhookDispatcher, SentinelConfig, WatcherDefinition, WatcherRuntimeState } from "./types.js";
+import { DeliveryTarget, GatewayWebhookDispatcher, SentinelConfig, WatcherDefinition, WatcherRuntimeState } from "./types.js";
+export declare const RESET_BACKOFF_AFTER_MS = 60000;
+export interface WatcherCreateContext {
+    deliveryTargets?: DeliveryTarget[];
+}
+export interface WatcherNotifier {
+    notify(target: DeliveryTarget, message: string): Promise<void>;
+}
+export declare const backoff: (base: number, max: number, failures: number) => number;
 export declare class WatcherManager {
     private config;
     private dispatcher;
+    private notifier?;
     private watchers;
     private runtime;
     private stops;
     private retryTimers;
     private statePath;
     private webhookRegistration;
-    constructor(config: SentinelConfig, dispatcher: GatewayWebhookDispatcher);
+    constructor(config: SentinelConfig, dispatcher: GatewayWebhookDispatcher, notifier?: WatcherNotifier | undefined);
     init(): Promise<void>;
-    create(input: unknown): Promise<WatcherDefinition>;
+    create(input: unknown, ctx?: WatcherCreateContext): Promise<WatcherDefinition>;
     list(): WatcherDefinition[];
     status(id: string): WatcherRuntimeState | undefined;
+    setNotifier(notifier: WatcherNotifier | undefined): void;
     setWebhookRegistrationStatus(status: "ok" | "error", message?: string, path?: string): void;
     enable(id: string): Promise<void>;
     disable(id: string): Promise<void>;

package/dist/watcherManager.js

@@ -3,12 +3,14 @@ import { assertHostAllowed, assertWatcherLimits } from "./limits.js";
 import { defaultStatePath, loadState, saveState } from "./stateStore.js";
 import { renderTemplate } from "./template.js";
 import { validateWatcherDefinition } from "./validator.js";
+import { createCallbackEnvelope } from "./callbackEnvelope.js";
 import { httpPollStrategy } from "./strategies/httpPoll.js";
 import { httpLongPollStrategy } from "./strategies/httpLongPoll.js";
 import { sseStrategy } from "./strategies/sse.js";
 import { websocketStrategy } from "./strategies/websocket.js";
 import { DEFAULT_SENTINEL_WEBHOOK_PATH, } from "./types.js";
-const backoff = (base, max, failures) => {
+export const RESET_BACKOFF_AFTER_MS = 60_000;
+export const backoff = (base, max, failures) => {
     const raw = Math.min(max, base * 2 ** failures);
     const jitter = Math.floor(raw * 0.25 * (Math.random() * 2 - 1));
     return Math.max(base, raw + jitter);
@@ -16,6 +18,7 @@ const backoff = (base, max, failures) => {
 export class WatcherManager {
     config;
     dispatcher;
+    notifier;
     watchers = new Map();
     runtime = {};
     stops = new Map();
@@ -25,9 +28,10 @@ export class WatcherManager {
         path: DEFAULT_SENTINEL_WEBHOOK_PATH,
         status: "pending",
     };
-    constructor(config, dispatcher) {
+    constructor(config, dispatcher, notifier) {
         this.config = config;
         this.dispatcher = dispatcher;
+        this.notifier = notifier;
         this.statePath = config.stateFilePath ?? defaultStatePath();
     }
     async init() {
@@ -41,28 +45,33 @@ export class WatcherManager {
                 this.watchers.set(watcher.id, watcher);
             }
             catch (err) {
+                const prev = this.runtime[rawWatcher.id];
                 this.runtime[rawWatcher.id] = {
                     id: rawWatcher.id,
-                    consecutiveFailures: (this.runtime[rawWatcher.id]?.consecutiveFailures ?? 0) + 1,
+                    consecutiveFailures: (prev?.consecutiveFailures ?? 0) + 1,
+                    reconnectAttempts: prev?.reconnectAttempts ?? 0,
                     lastError: `Invalid persisted watcher: ${String(err?.message ?? err)}`,
-                    lastResponseAt: this.runtime[rawWatcher.id]?.lastResponseAt,
-                    lastEvaluated: this.runtime[rawWatcher.id]?.lastEvaluated,
-                    lastPayloadHash: this.runtime[rawWatcher.id]?.lastPayloadHash,
-                    lastPayload: this.runtime[rawWatcher.id]?.lastPayload,
+                    lastResponseAt: prev?.lastResponseAt,
+                    lastEvaluated: prev?.lastEvaluated,
+                    lastPayloadHash: prev?.lastPayloadHash,
+                    lastPayload: prev?.lastPayload,
                 };
             }
         }
         for (const watcher of this.list().filter((w) => w.enabled))
             await this.startWatcher(watcher.id);
     }
-    async create(input) {
+    async create(input, ctx) {
         const watcher = validateWatcherDefinition(input);
+        if (!watcher.deliveryTargets?.length && ctx?.deliveryTargets?.length) {
+            watcher.deliveryTargets = ctx.deliveryTargets;
+        }
         assertHostAllowed(this.config, watcher.endpoint);
         assertWatcherLimits(this.config, this.list(), watcher);
         if (this.watchers.has(watcher.id))
             throw new Error(`Watcher already exists: ${watcher.id}`);
         this.watchers.set(watcher.id, watcher);
-        this.runtime[watcher.id] = { id: watcher.id, consecutiveFailures: 0 };
+        this.runtime[watcher.id] = { id: watcher.id, consecutiveFailures: 0, reconnectAttempts: 0 };
         if (watcher.enabled)
             await this.startWatcher(watcher.id);
         await this.persist();
@@ -74,6 +83,9 @@ export class WatcherManager {
     status(id) {
         return this.runtime[id];
     }
+    setNotifier(notifier) {
+        this.notifier = notifier;
+    }
     setWebhookRegistrationStatus(status, message, path) {
         this.webhookRegistration = {
             path: path ?? this.webhookRegistration.path,
@@ -117,9 +129,19 @@ export class WatcherManager {
             "http-long-poll": httpLongPollStrategy,
         }[watcher.strategy];
         const handleFailure = async (err) => {
-            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0 };
+            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0, reconnectAttempts: 0 };
+            rt.reconnectAttempts ??= 0;
+            const errMsg = String(err instanceof Error ? err.message : err);
+            rt.lastDisconnectAt = new Date().toISOString();
+            rt.lastDisconnectReason = errMsg;
+            rt.lastError = errMsg;
+            if (rt.lastConnectAt) {
+                const connectedMs = Date.now() - new Date(rt.lastConnectAt).getTime();
+                if (connectedMs >= RESET_BACKOFF_AFTER_MS) {
+                    rt.consecutiveFailures = 0;
+                }
+            }
             rt.consecutiveFailures += 1;
-            rt.lastError = String(err?.message ?? err);
             this.runtime[id] = rt;
             if (this.retryTimers.has(id)) {
                 await this.persist();
@@ -127,6 +149,7 @@ export class WatcherManager {
             }
             const delay = backoff(watcher.retry.baseMs, watcher.retry.maxMs, rt.consecutiveFailures);
             if (rt.consecutiveFailures <= watcher.retry.maxRetries && watcher.enabled) {
+                rt.reconnectAttempts += 1;
                 await this.stopWatcher(id);
                 const timer = setTimeout(() => {
                     this.retryTimers.delete(id);
@@ -137,7 +160,7 @@ export class WatcherManager {
             await this.persist();
         };
         const stop = await handler(watcher, async (payload) => {
-            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0 };
+            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0, reconnectAttempts: 0 };
             const previousPayload = rt.lastPayload;
             const matched = evaluateConditions(watcher.conditions, watcher.match, payload, previousPayload);
             rt.lastPayloadHash = hashPayload(payload);
@@ -145,23 +168,63 @@ export class WatcherManager {
             rt.lastResponseAt = new Date().toISOString();
             rt.lastEvaluated = rt.lastResponseAt;
             rt.consecutiveFailures = 0;
+            rt.reconnectAttempts = 0;
             rt.lastError = undefined;
             this.runtime[id] = rt;
             if (matched) {
-                const body = renderTemplate(watcher.fire.payloadTemplate, {
+                const matchedAt = new Date().toISOString();
+                const payloadBody = renderTemplate(watcher.fire.payloadTemplate, {
                     watcher,
                     event: { name: watcher.fire.eventName },
                     payload,
-                    timestamp: new Date().toISOString(),
+                    timestamp: matchedAt,
                 });
-                await this.dispatcher.dispatch(watcher.fire.webhookPath ?? DEFAULT_SENTINEL_WEBHOOK_PATH, body);
+                const webhookPath = watcher.fire.webhookPath ?? DEFAULT_SENTINEL_WEBHOOK_PATH;
+                const body = createCallbackEnvelope({
+                    watcher,
+                    payload,
+                    payloadBody,
+                    matchedAt,
+                    webhookPath,
+                });
+                await this.dispatcher.dispatch(webhookPath, body);
+                if (watcher.deliveryTargets?.length && this.notifier) {
+                    const attemptedAt = new Date().toISOString();
+                    const message = JSON.stringify(body);
+                    const failures = [];
+                    let successCount = 0;
+                    await Promise.all(watcher.deliveryTargets.map(async (target) => {
+                        try {
+                            await this.notifier?.notify(target, message);
+                            successCount += 1;
+                        }
+                        catch (err) {
+                            failures.push({
+                                target,
+                                error: String(err?.message ?? err),
+                            });
+                        }
+                    }));
+                    rt.lastDelivery = {
+                        attemptedAt,
+                        successCount,
+                        failureCount: failures.length,
+                        failures: failures.length > 0 ? failures : undefined,
+                    };
+                }
                 if (watcher.fireOnce) {
                     watcher.enabled = false;
                     await this.stopWatcher(id);
                 }
             }
             await this.persist();
-        }, handleFailure);
+        }, handleFailure, {
+            onConnect: () => {
+                const rt = this.runtime[id] ?? { id, consecutiveFailures: 0, reconnectAttempts: 0 };
+                rt.lastConnectAt = new Date().toISOString();
+                this.runtime[id] = rt;
+            },
+        });
         this.stops.set(id, stop);
     }
     async stopWatcher(id) {

package/openclaw.plugin.json

@@ -12,7 +12,6 @@
       },
       "localDispatchBase": {
         "type": "string",
-        "format": "uri",
         "description": "Base URL for internal webhook dispatch",
         "default": "http://127.0.0.1:18789"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeexdev/openclaw-sentinel",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",
@@ -29,18 +29,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "lint": "tsc --noEmit",
-    "format": "oxfmt --write .",
-    "format:check": "oxfmt --check .",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "changeset publish",
-    "prepack": "npm run build",
-    "prepare": "husky"
-  },
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
     "re2-wasm": "^1.0.2",
@@ -74,5 +62,16 @@
     "extensions": [
       "dist/index.js"
     ]
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:smoke-install": "./scripts/smoke-install.sh",
+    "lint": "tsc --noEmit",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
   }
-}
+}