@coffeexdev/openclaw-sentinel 0.3.0 → 0.4.1

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,25 +95,35 @@ Use `sentinel_control`:
 ## What happens when a watcher fires?
 
 1. Sentinel evaluates conditions.
-2. On match, it dispatches to `localDispatchBase + webhookPath`.
-3. 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).
-4. For `/hooks/sentinel`, the plugin route enqueues a system event (instruction prefix + structured JSON envelope) and requests heartbeat wake.
-5. 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).
 
-### `/hooks/sentinel` wake event format
+Sample emitted envelope:
 
-Sentinel enqueues deterministic system-event text in this shape:
-
-```text
-SENTINEL_TRIGGER: This system event came from /hooks/sentinel. Evaluate action policy, decide whether to notify configured deliveryTargets, and execute safe follow-up actions.
-SENTINEL_ENVELOPE_JSON:
-{ ...stable JSON 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" }
+}
 ```
 
-Envelope keys: `watcherId`, `eventName`, `skillId` (if present), `matchedAt`, `payload` (bounded with truncation marker when clipped), `dedupeKey`, `correlationId`, `deliveryTargets` (if present), `source` (`route`, `plugin`).
-
 ## Why Sentinel
 
 Sentinel runs watcher lifecycles inside the gateway with fixed strategies and declarative conditions.

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/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/templateValueSchema.d.ts

@@ -0,0 +1,2 @@
+export declare const TEMPLATE_VALUE_SCHEMA_ID = "https://schemas.coffeexcoin.dev/openclaw-sentinel/template-value.json";
+export declare const TemplateValueSchema: any;

package/dist/templateValueSchema.js

@@ -0,0 +1,10 @@
+import { Type } from "@sinclair/typebox";
+export const TEMPLATE_VALUE_SCHEMA_ID = "https://schemas.coffeexcoin.dev/openclaw-sentinel/template-value.json";
+export const TemplateValueSchema = Type.Recursive((Self) => Type.Union([
+    Type.String(),
+    Type.Number(),
+    Type.Boolean(),
+    Type.Null(),
+    Type.Array(Self),
+    Type.Record(Type.String(), Self),
+]), { $id: TEMPLATE_VALUE_SCHEMA_ID });

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;

package/dist/toolSchema.js

@@ -1,4 +1,5 @@
 import { Type } from "@sinclair/typebox";
+import { TemplateValueSchema } from "./templateValueSchema.js";
 const ConditionSchema = Type.Object({
     path: Type.String({ description: "JSONPath expression to evaluate against the response" }),
     op: Type.Union([
@@ -23,9 +24,16 @@ 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" }),

package/dist/types.d.ts

@@ -6,10 +6,16 @@ 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;

package/dist/validator.d.ts

@@ -1,2 +1,42 @@
 import { WatcherDefinition } from "./types.js";
+export declare const WatcherSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    skillId: import("@sinclair/typebox").TString;
+    enabled: import("@sinclair/typebox").TBoolean;
+    strategy: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"http-poll">, import("@sinclair/typebox").TLiteral<"websocket">, import("@sinclair/typebox").TLiteral<"sse">, import("@sinclair/typebox").TLiteral<"http-long-poll">]>;
+    endpoint: import("@sinclair/typebox").TString;
+    method: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"GET">, import("@sinclair/typebox").TLiteral<"POST">]>>;
+    headers: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    intervalMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    match: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"all">, import("@sinclair/typebox").TLiteral<"any">]>;
+    conditions: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        path: import("@sinclair/typebox").TString;
+        op: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"eq">, import("@sinclair/typebox").TLiteral<"neq">, import("@sinclair/typebox").TLiteral<"gt">, import("@sinclair/typebox").TLiteral<"gte">, import("@sinclair/typebox").TLiteral<"lt">, import("@sinclair/typebox").TLiteral<"lte">, import("@sinclair/typebox").TLiteral<"exists">, import("@sinclair/typebox").TLiteral<"absent">, import("@sinclair/typebox").TLiteral<"contains">, import("@sinclair/typebox").TLiteral<"matches">, import("@sinclair/typebox").TLiteral<"changed">]>;
+        value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnknown>;
+    }>>;
+    fire: import("@sinclair/typebox").TObject<{
+        webhookPath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        eventName: import("@sinclair/typebox").TString;
+        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").TInteger;
+        baseMs: import("@sinclair/typebox").TInteger;
+        maxMs: import("@sinclair/typebox").TInteger;
+    }>;
+    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>>;
+}>;
 export declare function validateWatcherDefinition(input: unknown): WatcherDefinition;

package/dist/validator.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 import { Value } from "@sinclair/typebox/value";
+import { TemplateValueSchema } from "./templateValueSchema.js";
 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;
@@ -20,7 +21,7 @@ const ConditionSchema = Type.Object({
     ]),
     value: Type.Optional(Type.Unknown()),
 }, { additionalProperties: false });
-const WatcherSchema = Type.Object({
+export const WatcherSchema = Type.Object({
     id: Type.String({ minLength: 1 }),
     skillId: Type.String({ minLength: 1 }),
     enabled: Type.Boolean(),
@@ -41,7 +42,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 }),

package/dist/watcherManager.js

@@ -3,6 +3,7 @@ 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";
@@ -171,13 +172,22 @@ export class WatcherManager {
             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);

package/package.json

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