@coffeexdev/openclaw-sentinel 0.1.7 → 0.2.0

package/README.md

@@ -2,16 +2,107 @@
 
 Secure, declarative, gateway-native background watcher plugin for OpenClaw.
 
+## Quick start (OpenClaw users)
+
+If you only read one section, read this.
+
+### 1) Install plugin
+
+```bash
+openclaw plugins install @coffeexdev/openclaw-sentinel
+```
+
+### 2) Configure Sentinel
+
+Add/update `~/.openclaw/openclaw.json`:
+
+```json5
+{
+  sentinel: {
+    // Required: watchers can only call endpoints on these hosts.
+    allowedHosts: ["api.github.com", "api.coingecko.com"],
+
+    // Default dispatch base for internal webhook callbacks.
+    localDispatchBase: "http://127.0.0.1:18789",
+
+    // Optional: where /hooks/sentinel events are queued in the LLM loop.
+    hookSessionKey: "agent:main:main",
+
+    // Optional: bearer token used for dispatch calls back to gateway.
+    // Set this to your gateway auth token when gateway auth is enabled.
+    // dispatchAuthToken: "<gateway-token>"
+  },
+}
+```
+
+### 3) Restart gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4) Create your first watcher (`sentinel_control`)
+
+```json
+{
+  "action": "create",
+  "watcher": {
+    "id": "eth-price-watch",
+    "skillId": "skills.alerts",
+    "enabled": true,
+    "strategy": "http-poll",
+    "endpoint": "https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd",
+    "intervalMs": 15000,
+    "match": "all",
+    "conditions": [{ "path": "ethereum.usd", "op": "gte", "value": 5000 }],
+    "fire": {
+      "webhookPath": "/hooks/sentinel",
+      "eventName": "eth_target_hit",
+      "payloadTemplate": {
+        "event": "${event.name}",
+        "price": "${payload.ethereum.usd}",
+        "ts": "${timestamp}"
+      }
+    },
+    "retry": { "maxRetries": 5, "baseMs": 500, "maxMs": 15000 },
+    "fireOnce": true
+  }
+}
+```
+
+### 5) Verify
+
+Use `sentinel_control`:
+
+```json
+{ "action": "list" }
+```
+
+```json
+{ "action": "status", "id": "eth-price-watch" }
+```
+
+---
+
+## 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`).
+
+The `/hooks/sentinel` route is auto-registered on plugin startup (idempotent).
+
 ## Why Sentinel
 
-OpenClaw Sentinel runs watcher lifecycles inside the gateway using fixed strategies and declarative conditions.
+Sentinel runs watcher lifecycles inside the gateway with fixed strategies and declarative conditions.
 It **does not** execute user-authored code from watcher definitions.
 
 ## Features
 
 - Tool registration: `sentinel_control`
   - actions: `create`, `enable`, `disable`, `remove`, `status`, `list`
-- Strict schema validation (`zod.strict`) + code-like field/value rejection
+- Strict schema validation (TypeBox, strict object checks) + code-like field/value rejection
 - Strategies:
   - `http-poll`
   - `websocket`
@@ -21,50 +112,13 @@ It **does not** execute user-authored code from watcher definitions.
   - `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `exists`, `absent`, `contains`, `matches`, `changed`
 - Match mode: `all` / `any`
 - Fire templating: substitution-only placeholders, non-Turing-complete
-- Fire route: local internal webhook dispatch path (no outbound fire URL)
+- Local webhook dispatch model (no outbound custom fire URL)
+- Default callback route: `/hooks/sentinel` (auto-registered)
 - Persistence: `~/.openclaw/sentinel-state.json`
 - Resource limits and per-skill limits
 - `allowedHosts` endpoint enforcement
 - CLI surface: `list`, `status`, `enable`, `disable`, `audit`
 
-## JSON Schema
-
-Formal JSON Schema for sentinel config/watchers is available at:
-
-- `schema/sentinel.schema.json`
-
-You can validate a watcher config document (for example `.sentinel.json`) against this schema in CI or local tooling.
-
-## Documentation
-
-- [Usage Guide](docs/USAGE.md)
-
-## Install
-
-```bash
-npm i @coffeexdev/openclaw-sentinel
-```
-
-## Quick usage
-
-No hosts are allowed by default — you must explicitly configure `allowedHosts` for watchers to connect to any endpoint.
-
-```ts
-import { createSentinelPlugin } from "@coffeexdev/openclaw-sentinel";
-
-const sentinel = createSentinelPlugin({
-  allowedHosts: ["api.github.com", "api.coingecko.com"],
-  localDispatchBase: "http://127.0.0.1:4389",
-});
-
-await sentinel.init();
-sentinel.register({
-  registerTool(name, handler) {
-    // gateway tool registry hook
-  },
-});
-```
-
 ## Tool input example (`sentinel_control:create`)
 
 ```json
@@ -72,7 +126,7 @@ sentinel.register({
   "action": "create",
   "watcher": {
     "id": "sentinel-alert",
-    "skillId": "skills.general-monitor"
+    "skillId": "skills.general-monitor",
     "enabled": true,
     "strategy": "http-poll",
     "endpoint": "https://api.github.com/events",
@@ -80,7 +134,7 @@ sentinel.register({
     "match": "any",
     "conditions": [{ "path": "type", "op": "eq", "value": "PushEvent" }],
     "fire": {
-      "webhookPath": "/internal/sentinel/fire",
+      "webhookPath": "/hooks/sentinel",
       "eventName": "sentinel_push",
       "payloadTemplate": {
         "watcher": "${watcher.id}",
@@ -94,72 +148,39 @@ sentinel.register({
 }
 ```
 
-## CLI
+## Runtime controls
 
-```bash
-openclaw-sentinel list
-openclaw-sentinel status <watcher-id>
-openclaw-sentinel enable <watcher-id>
-openclaw-sentinel disable <watcher-id>
-openclaw-sentinel audit
+```json
+{ "action": "status", "id": "sentinel-alert" }
 ```
 
-### One-shot watchers
-
-Set `"fireOnce": true` to automatically disable a watcher after its first matched event.
-
-## Example scenarios
-
-### Feed monitoring example
-
-Watch API changes and fire internal webhook events for orchestration.
-
-### Blockchain price watch
-
-`http-poll` against `api.coingecko.com`, `gt/lte/changed` conditions, routed to local webhook.
-
-### CI monitoring
-
-`sse` or `http-long-poll` against approved CI host endpoint; fire standardized internal events.
-
-## Security model
+```json
+{ "action": "disable", "id": "sentinel-alert" }
+```
 
-- No dynamic code execution from watcher definitions
-- No dynamic imports/requires from definitions
-- Strict input schema, unknown field rejection
-- Code-like fields/values rejected
-- Allowed-host enforcement on endpoints
-- Local-only fire routing through `localDispatchBase + webhookPath`
-- Bounded retries with backoff
-- Global/per-skill/condition limits
+```json
+{ "action": "remove", "id": "sentinel-alert" }
+```
 
-## Future Improvements
+## JSON Schema
 
-1. **WebSocket/SSE resilience tuning**
-   - Improve reconnect behavior and dedupe close+error failure handling.
-   - Add stronger circuit-breaker/backoff controls under bursty failures.
+Formal JSON Schema for sentinel config/watchers:
 
-2. **State persistence hardening**
-   - Add optional payload redaction or `do-not-persist-payload` mode so `lastPayload` does not store sensitive data on disk.
-   - Keep `changed` semantics while minimizing persisted sensitive fields.
+- `schema/sentinel.schema.json`
 
-3. **Dispatch integrity hardening**
-   - Add optional HMAC signing for internal webhook dispatch payloads in addition to bearer auth token support.
-   - Validate signature at receiver to prevent tampering in misconfigured local planes.
+## Documentation
 
-4. **Regex safety simplification and compatibility policy**
-   - Continue standardizing on `re2` with `re2-wasm` fallback.
-   - Document/centralize behavior for unsupported regex features (e.g., lookahead/backrefs).
+- [Usage Guide](docs/USAGE.md)
 
-5. **Lifecycle completeness**
-   - Add explicit `stopAll()` shutdown path in plugin lifecycle hooks for deterministic cleanup.
-   - Expand startup/reload behavior tests to ensure no orphaned watchers/timers.
+## CLI
 
-6. **Test coverage expansion (priority)**
-   - Add websocket reconnection/error-dedupe tests.
-   - Add retry/backoff timing behavior tests.
-   - Add state file permission assertions and payload persistence tests.
-   - Add dispatch auth matrix tests (token on/off).
+```bash
+openclaw-sentinel list
+openclaw-sentinel status <watcher-id>
+openclaw-sentinel enable <watcher-id>
+openclaw-sentinel disable <watcher-id>
+openclaw-sentinel audit
+```
 
 ## Development
 

package/dist/configSchema.js

@@ -1,22 +1,79 @@
-import { z } from "zod";
-const limitsSchema = z.object({
-    maxWatchersTotal: z.number().int().positive().default(200),
-    maxWatchersPerSkill: z.number().int().positive().default(20),
-    maxConditionsPerWatcher: z.number().int().positive().default(25),
-    maxIntervalMsFloor: z.number().int().positive().default(1000),
-});
-const configZodSchema = z.object({
-    allowedHosts: z.array(z.string()).default([]),
-    localDispatchBase: z.string().url().default("http://127.0.0.1:18789"),
-    dispatchAuthToken: z.string().optional(),
-    stateFilePath: z.string().optional(),
-    limits: limitsSchema.default({}),
-});
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+const LimitsSchema = Type.Object({
+    maxWatchersTotal: Type.Integer({ minimum: 1 }),
+    maxWatchersPerSkill: Type.Integer({ minimum: 1 }),
+    maxConditionsPerWatcher: Type.Integer({ minimum: 1 }),
+    maxIntervalMsFloor: Type.Integer({ minimum: 1 }),
+}, { additionalProperties: false });
+const ConfigSchema = Type.Object({
+    allowedHosts: Type.Array(Type.String()),
+    localDispatchBase: Type.String({ minLength: 1 }),
+    dispatchAuthToken: Type.Optional(Type.String()),
+    hookSessionKey: Type.Optional(Type.String({ minLength: 1 })),
+    stateFilePath: Type.Optional(Type.String()),
+    limits: Type.Optional(LimitsSchema),
+}, { additionalProperties: false });
+function withDefaults(value) {
+    const limitsIn = value.limits ?? {};
+    return {
+        allowedHosts: Array.isArray(value.allowedHosts) ? value.allowedHosts : [],
+        localDispatchBase: typeof value.localDispatchBase === "string" && value.localDispatchBase.length > 0
+            ? value.localDispatchBase
+            : "http://127.0.0.1:18789",
+        dispatchAuthToken: typeof value.dispatchAuthToken === "string" ? value.dispatchAuthToken : undefined,
+        hookSessionKey: typeof value.hookSessionKey === "string" ? value.hookSessionKey : "agent:main:main",
+        stateFilePath: typeof value.stateFilePath === "string" ? value.stateFilePath : undefined,
+        limits: {
+            maxWatchersTotal: typeof limitsIn.maxWatchersTotal === "number" ? limitsIn.maxWatchersTotal : 200,
+            maxWatchersPerSkill: typeof limitsIn.maxWatchersPerSkill === "number" ? limitsIn.maxWatchersPerSkill : 20,
+            maxConditionsPerWatcher: typeof limitsIn.maxConditionsPerWatcher === "number"
+                ? limitsIn.maxConditionsPerWatcher
+                : 25,
+            maxIntervalMsFloor: typeof limitsIn.maxIntervalMsFloor === "number" ? limitsIn.maxIntervalMsFloor : 1000,
+        },
+    };
+}
+function issue(path, message) {
+    const segments = path.replace(/^\//, "").split("/").filter(Boolean);
+    return {
+        path: segments,
+        message,
+    };
+}
 export const sentinelConfigSchema = {
     safeParse: (value) => {
         if (value === undefined)
             return { success: true, data: undefined };
-        return configZodSchema.safeParse(value);
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            return {
+                success: false,
+                error: { issues: [issue("/", "Config must be an object")] },
+            };
+        }
+        const candidate = withDefaults(value);
+        if (!Value.Check(ConfigSchema, candidate)) {
+            const first = [...Value.Errors(ConfigSchema, candidate)][0];
+            return {
+                success: false,
+                error: {
+                    issues: [issue(String(first?.path || "/"), String(first?.message || "Invalid config"))],
+                },
+            };
+        }
+        // explicit URL validation (TypeBox format validators are not enabled by default)
+        try {
+            new URL(candidate.localDispatchBase);
+        }
+        catch {
+            return {
+                success: false,
+                error: {
+                    issues: [issue("/localDispatchBase", "Invalid URL")],
+                },
+            };
+        }
+        return { success: true, data: candidate };
     },
     jsonSchema: {
         type: "object",
@@ -38,6 +95,11 @@ export const sentinelConfigSchema = {
                 type: "string",
                 description: "Bearer token for authenticating webhook dispatch requests",
             },
+            hookSessionKey: {
+                type: "string",
+                description: "Session key used when /hooks/sentinel enqueues system events into the LLM loop",
+                default: "agent:main:main",
+            },
             stateFilePath: {
                 type: "string",
                 description: "Custom path for the sentinel state persistence file",
@@ -86,6 +148,11 @@ export const sentinelConfigSchema = {
             sensitive: true,
             placeholder: "sk-...",
         },
+        hookSessionKey: {
+            label: "Sentinel Hook Session Key",
+            help: "Session key that receives /hooks/sentinel callback events (default: agent:main:main)",
+            advanced: true,
+        },
         stateFilePath: {
             label: "State File Path",
             help: "Custom path for sentinel state persistence file",

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { WatcherManager } from "./watcherManager.js";
 import { SentinelConfig } from "./types.js";
+import { WatcherManager } from "./watcherManager.js";
 export declare function createSentinelPlugin(overrides?: Partial<SentinelConfig>): {
     manager: WatcherManager;
     init(): Promise<void>;

package/dist/index.js

@@ -1,11 +1,81 @@
+import { sentinelConfigSchema } from "./configSchema.js";
 import { registerSentinelControl } from "./tool.js";
+import { DEFAULT_SENTINEL_WEBHOOK_PATH } from "./types.js";
 import { WatcherManager } from "./watcherManager.js";
-import { sentinelConfigSchema } from "./configSchema.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;
+}
+function trimText(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max)}…`;
+}
+function asString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+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);
+    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);
+}
+async function readSentinelWebhookPayload(req) {
+    const preParsed = req.body;
+    if (isRecord(preParsed))
+        return preParsed;
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const next = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        total += next.length;
+        if (total > MAX_SENTINEL_WEBHOOK_BODY_BYTES) {
+            throw new Error("Request body too large");
+        }
+        chunks.push(next);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Invalid JSON payload");
+    }
+    if (!isRecord(parsed)) {
+        throw new Error("Payload must be a JSON object");
+    }
+    return parsed;
+}
 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,
         limits: {
             maxWatchersTotal: 200,
             maxWatchersPerSkill: 20,
@@ -18,7 +88,7 @@ export function createSentinelPlugin(overrides) {
         async dispatch(path, body) {
             const headers = { "content-type": "application/json" };
             if (config.dispatchAuthToken)
-                headers["authorization"] = `Bearer ${config.dispatchAuthToken}`;
+                headers.authorization = `Bearer ${config.dispatchAuthToken}`;
             await fetch(`${config.localDispatchBase}${path}`, {
                 method: "POST",
                 headers,
@@ -33,6 +103,68 @@ export function createSentinelPlugin(overrides) {
         },
         register(api) {
             registerSentinelControl(api.registerTool.bind(api), manager);
+            const path = normalizePath(DEFAULT_SENTINEL_WEBHOOK_PATH);
+            if (!api.registerHttpRoute) {
+                const msg = "registerHttpRoute API not available; default sentinel webhook route was not registered";
+                manager.setWebhookRegistrationStatus("error", msg, path);
+                api.logger?.error?.(`[openclaw-sentinel] ${msg}`);
+                return;
+            }
+            const registrarKey = api.registerHttpRoute;
+            const registeredPaths = registeredWebhookPathsByRegistrar.get(registrarKey) ?? new Set();
+            registeredWebhookPathsByRegistrar.set(registrarKey, registeredPaths);
+            if (registeredPaths.has(path)) {
+                manager.setWebhookRegistrationStatus("ok", "Route already registered (idempotent)", path);
+                return;
+            }
+            try {
+                api.registerHttpRoute({
+                    path,
+                    auth: "gateway",
+                    match: "exact",
+                    replaceExisting: true,
+                    async handler(req, res) {
+                        if (req.method !== "POST") {
+                            res.writeHead(405, { "content-type": "application/json" });
+                            res.end(JSON.stringify({ error: "Method not allowed" }));
+                            return;
+                        }
+                        try {
+                            const payload = await readSentinelWebhookPayload(req);
+                            const sessionKey = config.hookSessionKey ?? DEFAULT_HOOK_SESSION_KEY;
+                            const text = buildSentinelSystemEvent(payload);
+                            const enqueued = api.runtime.system.enqueueSystemEvent(text, { sessionKey });
+                            api.runtime.system.requestHeartbeatNow({
+                                reason: "hook:sentinel",
+                                sessionKey,
+                            });
+                            res.writeHead(200, { "content-type": "application/json" });
+                            res.end(JSON.stringify({
+                                ok: true,
+                                route: path,
+                                sessionKey,
+                                enqueued,
+                            }));
+                        }
+                        catch (err) {
+                            const message = String(err?.message ?? err);
+                            const badRequest = message.includes("Invalid JSON payload") ||
+                                message.includes("Payload must be a JSON object");
+                            const status = message.includes("too large") ? 413 : badRequest ? 400 : 500;
+                            res.writeHead(status, { "content-type": "application/json" });
+                            res.end(JSON.stringify({ error: message }));
+                        }
+                    },
+                });
+                registeredPaths.add(path);
+                manager.setWebhookRegistrationStatus("ok", "Route registered", path);
+                api.logger?.info?.(`[openclaw-sentinel] Registered default webhook route ${path}`);
+            }
+            catch (err) {
+                const msg = `Failed to register default webhook route ${path}: ${String(err?.message ?? err)}`;
+                manager.setWebhookRegistrationStatus("error", msg, path);
+                api.logger?.error?.(`[openclaw-sentinel] ${msg}`);
+            }
         },
     };
 }

package/dist/types.d.ts

@@ -5,8 +5,9 @@ export interface Condition {
     op: Operator;
     value?: unknown;
 }
+export declare const DEFAULT_SENTINEL_WEBHOOK_PATH = "/hooks/sentinel";
 export interface FireConfig {
-    webhookPath: string;
+    webhookPath?: string;
     eventName: string;
     payloadTemplate: Record<string, string | number | boolean | null>;
 }
@@ -57,6 +58,7 @@ export interface SentinelConfig {
     allowedHosts: string[];
     localDispatchBase: string;
     dispatchAuthToken?: string;
+    hookSessionKey?: string;
     stateFilePath?: string;
     limits: SentinelLimits;
 }

package/dist/types.js

@@ -1 +1 @@
-export {};
+export const DEFAULT_SENTINEL_WEBHOOK_PATH = "/hooks/sentinel";

package/dist/validator.js

@@ -1,5 +1,6 @@
 import { Type } from "@sinclair/typebox";
 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 ConditionSchema = Type.Object({
@@ -38,7 +39,7 @@ const WatcherSchema = Type.Object({
     match: Type.Union([Type.Literal("all"), Type.Literal("any")]),
     conditions: Type.Array(ConditionSchema, { minItems: 1 }),
     fire: Type.Object({
-        webhookPath: Type.String({ pattern: "^/" }),
+        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()])),
     }, { additionalProperties: false }),
@@ -89,5 +90,12 @@ export function validateWatcherDefinition(input) {
     catch {
         throw new Error("Invalid watcher definition at /endpoint: Invalid URL");
     }
-    return input;
+    const watcher = input;
+    return {
+        ...watcher,
+        fire: {
+            ...watcher.fire,
+            webhookPath: watcher.fire.webhookPath ?? DEFAULT_SENTINEL_WEBHOOK_PATH,
+        },
+    };
 }

package/dist/watcherManager.d.ts

@@ -7,11 +7,13 @@ export declare class WatcherManager {
     private stops;
     private retryTimers;
     private statePath;
+    private webhookRegistration;
     constructor(config: SentinelConfig, dispatcher: GatewayWebhookDispatcher);
     init(): Promise<void>;
     create(input: unknown): Promise<WatcherDefinition>;
     list(): WatcherDefinition[];
     status(id: string): WatcherRuntimeState | undefined;
+    setWebhookRegistrationStatus(status: "ok" | "error", message?: string, path?: string): void;
     enable(id: string): Promise<void>;
     disable(id: string): Promise<void>;
     remove(id: string): Promise<void>;

package/dist/watcherManager.js

@@ -7,6 +7,7 @@ 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) => {
     const raw = Math.min(max, base * 2 ** failures);
     const jitter = Math.floor(raw * 0.25 * (Math.random() * 2 - 1));
@@ -20,6 +21,10 @@ export class WatcherManager {
     stops = new Map();
     retryTimers = new Map();
     statePath;
+    webhookRegistration = {
+        path: DEFAULT_SENTINEL_WEBHOOK_PATH,
+        status: "pending",
+    };
     constructor(config, dispatcher) {
         this.config = config;
         this.dispatcher = dispatcher;
@@ -69,6 +74,14 @@ export class WatcherManager {
     status(id) {
         return this.runtime[id];
     }
+    setWebhookRegistrationStatus(status, message, path) {
+        this.webhookRegistration = {
+            path: path ?? this.webhookRegistration.path,
+            status,
+            message,
+            updatedAt: new Date().toISOString(),
+        };
+    }
     async enable(id) {
         const w = this.require(id);
         w.enabled = true;
@@ -141,7 +154,7 @@ export class WatcherManager {
                     payload,
                     timestamp: new Date().toISOString(),
                 });
-                await this.dispatcher.dispatch(watcher.fire.webhookPath, body);
+                await this.dispatcher.dispatch(watcher.fire.webhookPath ?? DEFAULT_SENTINEL_WEBHOOK_PATH, body);
                 if (watcher.fireOnce) {
                     watcher.enabled = false;
                     await this.stopWatcher(id);
@@ -177,6 +190,7 @@ export class WatcherManager {
             allowedHosts: this.config.allowedHosts,
             limits: this.config.limits,
             statePath: this.statePath,
+            webhookRegistration: this.webhookRegistration,
         };
     }
     async persist() {

package/openclaw.plugin.json

@@ -20,6 +20,11 @@
         "type": "string",
         "description": "Bearer token for authenticating webhook dispatch requests"
       },
+      "hookSessionKey": {
+        "type": "string",
+        "description": "Session key used when /hooks/sentinel enqueues system events into the LLM loop",
+        "default": "agent:main:main"
+      },
       "stateFilePath": {
         "type": "string",
         "description": "Custom path for the sentinel state persistence file"
@@ -68,6 +73,11 @@
       "sensitive": true,
       "placeholder": "sk-..."
     },
+    "hookSessionKey": {
+      "label": "Sentinel Hook Session Key",
+      "help": "Session key that receives /hooks/sentinel callback events (default: agent:main:main)",
+      "advanced": true
+    },
     "stateFilePath": {
       "label": "State File Path",
       "help": "Custom path for sentinel state persistence file",

package/package.json

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