@coffeexdev/openclaw-sentinel 0.1.0 → 0.1.1

package/README.md

@@ -167,7 +167,3 @@ npm run build
 ## License
 
 MIT
-
-CI trigger probe: 2026-03-03T22:51:37Z
-
-Push trigger probe 2026-03-03T22:56:44Z

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { createSentinelPlugin } from "./index.js";
+const [cmd, arg] = process.argv.slice(2);
+const plugin = createSentinelPlugin();
+await plugin.init();
+switch (cmd) {
+    case "list":
+        console.log(JSON.stringify(plugin.manager.list(), null, 2));
+        break;
+    case "status":
+        console.log(JSON.stringify(plugin.manager.status(arg || ""), null, 2));
+        break;
+    case "enable":
+        await plugin.manager.enable(arg || "");
+        console.log("ok");
+        break;
+    case "disable":
+        await plugin.manager.disable(arg || "");
+        console.log("ok");
+        break;
+    case "audit":
+        console.log(JSON.stringify(await plugin.manager.audit(), null, 2));
+        break;
+    default:
+        console.log("Usage: openclaw-sentinel <list|status <id>|enable <id>|disable <id>|audit>");
+}

package/dist/evaluator.d.ts

@@ -0,0 +1,4 @@
+import { Condition } from "./types.js";
+export declare function evaluateCondition(condition: Condition, payload: unknown, previousPayload: unknown): boolean;
+export declare function evaluateConditions(conditions: Condition[], match: "all" | "any", payload: unknown, previousPayload: unknown): boolean;
+export declare function hashPayload(payload: unknown): string;

package/dist/evaluator.js

@@ -0,0 +1,94 @@
+import crypto from "node:crypto";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+let cachedRegexCtor = null;
+function getSafeRegexCtor() {
+    if (cachedRegexCtor)
+        return cachedRegexCtor;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const re2Mod = require("re2");
+        const RE2Ctor = (re2Mod?.default ?? re2Mod);
+        cachedRegexCtor = RE2Ctor;
+        return cachedRegexCtor;
+    }
+    catch {
+        // fallback below
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const re2Wasm = require("re2-wasm");
+        const RE2Ctor = (re2Wasm?.RE2 ?? re2Wasm?.default ?? re2Wasm);
+        cachedRegexCtor = RE2Ctor;
+        return cachedRegexCtor;
+    }
+    catch {
+        throw new Error("No safe regex engine available (re2/re2-wasm)");
+    }
+}
+function getPath(obj, path) {
+    return path.split(".").reduce((acc, part) => acc?.[part], obj);
+}
+function safeRegexTest(pattern, input) {
+    if (pattern.length > 256)
+        throw new Error("Regex pattern too long");
+    if (input.length > 4096)
+        throw new Error("Regex input too long");
+    // basic catastrophic pattern guard
+    if (/\([^)]*\|[^)]*\)[+*{]/.test(pattern) ||
+        (/\([^)]*\|[^)]*\)/.test(pattern) && /[+*{]/.test(pattern))) {
+        throw new Error("Potentially unsafe regex pattern rejected");
+    }
+    try {
+        const RE2Ctor = getSafeRegexCtor();
+        const flags = "u";
+        return new RE2Ctor(pattern, flags).test(input);
+    }
+    catch (err) {
+        const msg = String(err?.message ?? err);
+        if (msg.toLowerCase().includes("safe regex engine"))
+            throw err;
+        throw new Error("Invalid or unsupported regex pattern");
+    }
+}
+export function evaluateCondition(condition, payload, previousPayload) {
+    const current = getPath(payload, condition.path);
+    const previous = getPath(previousPayload, condition.path);
+    switch (condition.op) {
+        case "eq":
+            return current === condition.value;
+        case "neq":
+            return current !== condition.value;
+        case "gt":
+            return Number(current) > Number(condition.value);
+        case "gte":
+            return Number(current) >= Number(condition.value);
+        case "lt":
+            return Number(current) < Number(condition.value);
+        case "lte":
+            return Number(current) <= Number(condition.value);
+        case "exists":
+            return current !== undefined && current !== null;
+        case "absent":
+            return current === undefined || current === null;
+        case "contains":
+            return typeof current === "string"
+                ? current.includes(String(condition.value ?? ""))
+                : Array.isArray(current)
+                    ? current.includes(condition.value)
+                    : false;
+        case "matches":
+            return safeRegexTest(String(condition.value ?? ""), String(current ?? ""));
+        case "changed":
+            return JSON.stringify(current) !== JSON.stringify(previous);
+        default:
+            return false;
+    }
+}
+export function evaluateConditions(conditions, match, payload, previousPayload) {
+    const results = conditions.map((c) => evaluateCondition(c, payload, previousPayload));
+    return match === "all" ? results.every(Boolean) : results.some(Boolean);
+}
+export function hashPayload(payload) {
+    return crypto.createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { WatcherManager } from "./watcherManager.js";
+import { SentinelConfig } from "./types.js";
+export declare function createSentinelPlugin(overrides?: Partial<SentinelConfig>): {
+    manager: WatcherManager;
+    init(): Promise<void>;
+    register(api: {
+        registerTool: (name: string, handler: (input: unknown) => Promise<unknown>) => void;
+    }): void;
+};
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,38 @@
+import { registerSentinelControl } from "./tool.js";
+import { WatcherManager } from "./watcherManager.js";
+export function createSentinelPlugin(overrides) {
+    const config = {
+        allowedHosts: ["api.github.com", "api.coingecko.com", "example.com"],
+        localDispatchBase: "http://127.0.0.1:18789",
+        dispatchAuthToken: process.env.SENTINEL_DISPATCH_TOKEN,
+        limits: {
+            maxWatchersTotal: 200,
+            maxWatchersPerSkill: 20,
+            maxConditionsPerWatcher: 25,
+            maxIntervalMsFloor: 1000,
+        },
+        ...overrides,
+    };
+    const manager = new WatcherManager(config, {
+        async dispatch(path, body) {
+            const headers = { "content-type": "application/json" };
+            if (config.dispatchAuthToken)
+                headers["authorization"] = `Bearer ${config.dispatchAuthToken}`;
+            await fetch(`${config.localDispatchBase}${path}`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+            });
+        },
+    });
+    return {
+        manager,
+        async init() {
+            await manager.init();
+        },
+        register(api) {
+            registerSentinelControl(api.registerTool, manager);
+        },
+    };
+}
+export * from "./types.js";

package/dist/limits.d.ts

@@ -0,0 +1,3 @@
+import { SentinelConfig, WatcherDefinition } from "./types.js";
+export declare function assertWatcherLimits(config: SentinelConfig, watchers: WatcherDefinition[], incoming: WatcherDefinition): void;
+export declare function assertHostAllowed(config: SentinelConfig, endpoint: string): void;

package/dist/limits.js

@@ -0,0 +1,27 @@
+function normalizeHost(host) {
+    return host.trim().toLowerCase().replace(/\.$/, "");
+}
+export function assertWatcherLimits(config, watchers, incoming) {
+    if (watchers.length >= config.limits.maxWatchersTotal) {
+        throw new Error(`Watcher limit reached: ${config.limits.maxWatchersTotal}`);
+    }
+    const perSkill = watchers.filter((w) => w.skillId === incoming.skillId).length;
+    if (perSkill >= config.limits.maxWatchersPerSkill) {
+        throw new Error(`Per-skill watcher limit reached for ${incoming.skillId}: ${config.limits.maxWatchersPerSkill}`);
+    }
+    if (incoming.conditions.length > config.limits.maxConditionsPerWatcher) {
+        throw new Error(`Too many conditions: ${incoming.conditions.length}`);
+    }
+    if ((incoming.intervalMs ?? config.limits.maxIntervalMsFloor) < config.limits.maxIntervalMsFloor) {
+        throw new Error(`intervalMs too low; minimum is ${config.limits.maxIntervalMsFloor}`);
+    }
+}
+export function assertHostAllowed(config, endpoint) {
+    const parsed = new URL(endpoint);
+    const endpointHost = normalizeHost(parsed.hostname);
+    const endpointHostWithPort = normalizeHost(parsed.host);
+    const allowed = new Set(config.allowedHosts.map(normalizeHost));
+    if (!allowed.has(endpointHost) && !allowed.has(endpointHostWithPort)) {
+        throw new Error(`Host not allowed: ${parsed.host}`);
+    }
+}

package/dist/stateStore.d.ts

@@ -0,0 +1,5 @@
+import { SentinelStateFile, WatcherDefinition, WatcherRuntimeState } from "./types.js";
+export declare function defaultStatePath(): string;
+export declare function loadState(filePath: string): Promise<SentinelStateFile>;
+export declare function saveState(filePath: string, watchers: WatcherDefinition[], runtime: Record<string, WatcherRuntimeState>): Promise<void>;
+export declare function mergeState(existing: SentinelStateFile, incoming: SentinelStateFile): SentinelStateFile;

package/dist/stateStore.js

@@ -0,0 +1,35 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+export function defaultStatePath() {
+    return path.join(os.homedir(), ".openclaw", "sentinel-state.json");
+}
+export async function loadState(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            watchers: parsed.watchers ?? [],
+            runtime: parsed.runtime ?? {},
+            updatedAt: parsed.updatedAt ?? new Date().toISOString(),
+        };
+    }
+    catch {
+        return { watchers: [], runtime: {}, updatedAt: new Date().toISOString() };
+    }
+}
+export async function saveState(filePath, watchers, runtime) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    await fs.writeFile(filePath, JSON.stringify({ watchers, runtime, updatedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+    await fs.chmod(filePath, 0o600);
+}
+export function mergeState(existing, incoming) {
+    const watcherMap = new Map(existing.watchers.map((w) => [w.id, w]));
+    for (const watcher of incoming.watchers)
+        watcherMap.set(watcher.id, watcher);
+    return {
+        watchers: [...watcherMap.values()],
+        runtime: { ...existing.runtime, ...incoming.runtime },
+        updatedAt: new Date().toISOString(),
+    };
+}

package/dist/strategies/base.d.ts

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

package/dist/strategies/base.js

@@ -0,0 +1 @@
+export {};

package/dist/strategies/httpLongPoll.d.ts

@@ -0,0 +1,2 @@
+import { StrategyHandler } from "./base.js";
+export declare const httpLongPollStrategy: StrategyHandler;

package/dist/strategies/httpLongPoll.js

@@ -0,0 +1,29 @@
+export const httpLongPollStrategy = async (watcher, onPayload, onError) => {
+    let active = true;
+    const loop = async () => {
+        while (active) {
+            try {
+                const response = await fetch(watcher.endpoint, {
+                    method: watcher.method ?? "GET",
+                    headers: watcher.headers,
+                    body: watcher.body,
+                    signal: AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                });
+                if (!response.ok)
+                    throw new Error(`http-long-poll non-2xx: ${response.status}`);
+                const contentType = response.headers.get("content-type") ?? "";
+                if (!contentType.toLowerCase().includes("json"))
+                    throw new Error(`http-long-poll expected JSON, got: ${contentType || "unknown"}`);
+                await onPayload(await response.json());
+            }
+            catch (err) {
+                await onError(err);
+                return;
+            }
+        }
+    };
+    void loop();
+    return async () => {
+        active = false;
+    };
+};

package/dist/strategies/httpPoll.d.ts

@@ -0,0 +1,2 @@
+import { StrategyHandler } from "./base.js";
+export declare const httpPollStrategy: StrategyHandler;

package/dist/strategies/httpPoll.js

@@ -0,0 +1,35 @@
+export const httpPollStrategy = async (watcher, onPayload, onError) => {
+    const interval = watcher.intervalMs ?? 30000;
+    let active = true;
+    const tick = async () => {
+        if (!active)
+            return;
+        try {
+            const response = await fetch(watcher.endpoint, {
+                method: watcher.method ?? "GET",
+                headers: watcher.headers,
+                body: watcher.body,
+                signal: AbortSignal.timeout(watcher.timeoutMs ?? 15000),
+            });
+            if (!response.ok)
+                throw new Error(`http-poll non-2xx: ${response.status}`);
+            const contentType = response.headers.get("content-type") ?? "";
+            if (!contentType.toLowerCase().includes("json"))
+                throw new Error(`http-poll expected JSON, got: ${contentType || "unknown"}`);
+            const payload = await response.json();
+            await onPayload(payload);
+        }
+        catch (err) {
+            await onError(err);
+            return;
+        }
+        if (active)
+            setTimeout(() => {
+                void tick();
+            }, interval);
+    };
+    void tick();
+    return async () => {
+        active = false;
+    };
+};

package/dist/strategies/sse.d.ts

@@ -0,0 +1,2 @@
+import { StrategyHandler } from "./base.js";
+export declare const sseStrategy: StrategyHandler;

package/dist/strategies/sse.js

@@ -0,0 +1,41 @@
+export const sseStrategy = async (watcher, onPayload, onError) => {
+    let active = true;
+    const loop = async () => {
+        while (active) {
+            try {
+                const response = await fetch(watcher.endpoint, {
+                    headers: { Accept: "text/event-stream", ...(watcher.headers ?? {}) },
+                    signal: AbortSignal.timeout(watcher.timeoutMs ?? 60000),
+                });
+                if (!response.ok)
+                    throw new Error(`sse non-2xx: ${response.status}`);
+                const contentType = response.headers.get("content-type") ?? "";
+                if (!contentType.toLowerCase().includes("text/event-stream"))
+                    throw new Error(`sse expected text/event-stream, got: ${contentType || "unknown"}`);
+                const text = await response.text();
+                for (const line of text.split("\n")) {
+                    if (line.startsWith("data:")) {
+                        const raw = line.slice(5).trim();
+                        if (!raw)
+                            continue;
+                        try {
+                            await onPayload(JSON.parse(raw));
+                        }
+                        catch {
+                            await onPayload({ message: raw });
+                        }
+                    }
+                }
+                await new Promise((r) => setTimeout(r, watcher.intervalMs ?? 1000));
+            }
+            catch (err) {
+                await onError(err);
+                return;
+            }
+        }
+    };
+    void loop();
+    return async () => {
+        active = false;
+    };
+};

package/dist/strategies/websocket.d.ts

@@ -0,0 +1,2 @@
+import { StrategyHandler } from "./base.js";
+export declare const websocketStrategy: StrategyHandler;

package/dist/strategies/websocket.js

@@ -0,0 +1,35 @@
+import WebSocket from "ws";
+export const websocketStrategy = async (watcher, onPayload, onError) => {
+    let active = true;
+    let ws = null;
+    const connect = () => {
+        ws = new WebSocket(watcher.endpoint, { headers: watcher.headers });
+        ws.on("message", async (data) => {
+            if (!active)
+                return;
+            const text = data.toString();
+            try {
+                await onPayload(JSON.parse(text));
+            }
+            catch {
+                await onPayload({ message: text });
+            }
+        });
+        ws.on("error", (err) => {
+            if (!active)
+                return;
+            void onError(err);
+        });
+        ws.on("close", (code) => {
+            if (!active)
+                return;
+            void onError(new Error(`websocket closed: ${code}`));
+        });
+    };
+    connect();
+    return async () => {
+        active = false;
+        if (ws && ws.readyState === WebSocket.OPEN)
+            ws.close();
+    };
+};

package/dist/template.d.ts

@@ -0,0 +1 @@
+export declare function renderTemplate(template: Record<string, string | number | boolean | null>, context: Record<string, unknown>): Record<string, unknown>;

package/dist/template.js

@@ -0,0 +1,26 @@
+const placeholderPattern = /^\$\{(watcher\.(id|skillId)|event\.(name)|payload\.[a-zA-Z0-9_.-]+|timestamp)\}$/;
+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;
+        }
+        if (!placeholderPattern.test(value)) {
+            throw new Error(`Template placeholder not allowed: ${value}`);
+        }
+        const path = value.slice(2, -1);
+        const resolved = getPath(context, path);
+        if (resolved === undefined)
+            throw new Error(`Template placeholder unresolved: ${value}`);
+        out[key] = resolved;
+    }
+    return out;
+}

package/dist/tool.d.ts

@@ -0,0 +1,2 @@
+import { WatcherManager } from "./watcherManager.js";
+export declare function registerSentinelControl(registerTool: (name: string, handler: (input: unknown) => Promise<unknown>) => void, manager: WatcherManager): void;

package/dist/tool.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+const inputSchema = z
+    .object({
+    action: z.enum(["create", "enable", "disable", "remove", "status", "list"]),
+    id: z.string().optional(),
+    watcher: z.unknown().optional(),
+})
+    .strict();
+export function registerSentinelControl(registerTool, manager) {
+    registerTool("sentinel_control", async (input) => {
+        const parsed = inputSchema.parse(input);
+        switch (parsed.action) {
+            case "create":
+                return manager.create(parsed.watcher);
+            case "enable":
+                if (!parsed.id)
+                    throw new Error("id required");
+                await manager.enable(parsed.id);
+                return { ok: true };
+            case "disable":
+                if (!parsed.id)
+                    throw new Error("id required");
+                await manager.disable(parsed.id);
+                return { ok: true };
+            case "remove":
+                if (!parsed.id)
+                    throw new Error("id required");
+                await manager.remove(parsed.id);
+                return { ok: true };
+            case "status":
+                if (!parsed.id)
+                    throw new Error("id required");
+                return manager.status(parsed.id);
+            case "list":
+                return manager.list();
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,65 @@
+export type Strategy = "http-poll" | "websocket" | "sse" | "http-long-poll";
+export type Operator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "exists" | "absent" | "contains" | "matches" | "changed";
+export interface Condition {
+    path: string;
+    op: Operator;
+    value?: unknown;
+}
+export interface FireConfig {
+    webhookPath: string;
+    eventName: string;
+    payloadTemplate: Record<string, string | number | boolean | null>;
+}
+export interface RetryPolicy {
+    maxRetries: number;
+    baseMs: number;
+    maxMs: number;
+}
+export interface WatcherDefinition {
+    id: string;
+    skillId: string;
+    enabled: boolean;
+    strategy: Strategy;
+    endpoint: string;
+    method?: "GET" | "POST";
+    headers?: Record<string, string>;
+    body?: string;
+    intervalMs?: number;
+    timeoutMs?: number;
+    match: "all" | "any";
+    conditions: Condition[];
+    fire: FireConfig;
+    retry: RetryPolicy;
+    fireOnce?: boolean;
+    metadata?: Record<string, string>;
+}
+export interface WatcherRuntimeState {
+    id: string;
+    lastError?: string;
+    lastResponseAt?: string;
+    consecutiveFailures: number;
+    lastPayloadHash?: string;
+    lastPayload?: unknown;
+    lastEvaluated?: string;
+}
+export interface SentinelStateFile {
+    watchers: WatcherDefinition[];
+    runtime: Record<string, WatcherRuntimeState>;
+    updatedAt: string;
+}
+export interface SentinelLimits {
+    maxWatchersTotal: number;
+    maxWatchersPerSkill: number;
+    maxConditionsPerWatcher: number;
+    maxIntervalMsFloor: number;
+}
+export interface SentinelConfig {
+    allowedHosts: string[];
+    localDispatchBase: string;
+    dispatchAuthToken?: string;
+    stateFilePath?: string;
+    limits: SentinelLimits;
+}
+export interface GatewayWebhookDispatcher {
+    dispatch(path: string, body: Record<string, unknown>): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,2 @@
+import { WatcherDefinition } from "./types.js";
+export declare function validateWatcherDefinition(input: unknown): WatcherDefinition;

package/dist/validator.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+const codeyKeyPattern = /(script|code|eval|handler|function|import|require)/i;
+const codeyValuePattern = /(=>|\bfunction\b|\bimport\s+|\brequire\s*\(|\beval\s*\()/i;
+const conditionSchema = z
+    .object({
+    path: z.string().min(1),
+    op: z.enum([
+        "eq",
+        "neq",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "exists",
+        "absent",
+        "contains",
+        "matches",
+        "changed",
+    ]),
+    value: z.any().optional(),
+})
+    .strict();
+const watcherSchema = z
+    .object({
+    id: z.string().min(1),
+    skillId: z.string().min(1),
+    enabled: z.boolean().default(true),
+    strategy: z.enum(["http-poll", "websocket", "sse", "http-long-poll"]),
+    endpoint: z.string().url(),
+    method: z.enum(["GET", "POST"]).optional(),
+    headers: z.record(z.string()).optional(),
+    body: z.string().optional(),
+    intervalMs: z.number().int().positive().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    match: z.enum(["all", "any"]),
+    conditions: z.array(conditionSchema).min(1),
+    fire: z
+        .object({
+        webhookPath: z.string().regex(/^\//),
+        eventName: z.string().min(1),
+        payloadTemplate: z.record(z.union([z.string(), z.number(), z.boolean(), z.null()])),
+    })
+        .strict(),
+    retry: z
+        .object({
+        maxRetries: z.number().int().min(0).max(20),
+        baseMs: z.number().int().min(50).max(60000),
+        maxMs: z.number().int().min(100).max(300000),
+    })
+        .strict(),
+    fireOnce: z.boolean().optional(),
+    metadata: z.record(z.string()).optional(),
+})
+    .strict();
+function scanNoCodeLike(input, parentKey = "") {
+    if (input === null || input === undefined)
+        return;
+    if (typeof input === "string") {
+        if (codeyValuePattern.test(input))
+            throw new Error(`Code-like value rejected at ${parentKey || "<root>"}`);
+        return;
+    }
+    if (Array.isArray(input)) {
+        input.forEach((v, i) => scanNoCodeLike(v, `${parentKey}[${i}]`));
+        return;
+    }
+    if (typeof input === "object") {
+        for (const [key, value] of Object.entries(input)) {
+            if (codeyKeyPattern.test(key))
+                throw new Error(`Code-like field rejected: ${parentKey ? `${parentKey}.` : ""}${key}`);
+            scanNoCodeLike(value, parentKey ? `${parentKey}.${key}` : key);
+        }
+    }
+}
+export function validateWatcherDefinition(input) {
+    scanNoCodeLike(input);
+    return watcherSchema.parse(input);
+}

package/dist/watcherManager.d.ts

@@ -0,0 +1,23 @@
+import { GatewayWebhookDispatcher, SentinelConfig, WatcherDefinition, WatcherRuntimeState } from "./types.js";
+export declare class WatcherManager {
+    private config;
+    private dispatcher;
+    private watchers;
+    private runtime;
+    private stops;
+    private retryTimers;
+    private statePath;
+    constructor(config: SentinelConfig, dispatcher: GatewayWebhookDispatcher);
+    init(): Promise<void>;
+    create(input: unknown): Promise<WatcherDefinition>;
+    list(): WatcherDefinition[];
+    status(id: string): WatcherRuntimeState | undefined;
+    enable(id: string): Promise<void>;
+    disable(id: string): Promise<void>;
+    remove(id: string): Promise<void>;
+    private require;
+    private startWatcher;
+    private stopWatcher;
+    audit(): Promise<Record<string, unknown>>;
+    private persist;
+}

package/dist/watcherManager.js

@@ -0,0 +1,185 @@
+import { evaluateConditions, hashPayload } from "./evaluator.js";
+import { assertHostAllowed, assertWatcherLimits } from "./limits.js";
+import { defaultStatePath, loadState, saveState } from "./stateStore.js";
+import { renderTemplate } from "./template.js";
+import { validateWatcherDefinition } from "./validator.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";
+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);
+};
+export class WatcherManager {
+    config;
+    dispatcher;
+    watchers = new Map();
+    runtime = {};
+    stops = new Map();
+    retryTimers = new Map();
+    statePath;
+    constructor(config, dispatcher) {
+        this.config = config;
+        this.dispatcher = dispatcher;
+        this.statePath = config.stateFilePath ?? defaultStatePath();
+    }
+    async init() {
+        const state = await loadState(this.statePath);
+        this.runtime = state.runtime;
+        for (const rawWatcher of state.watchers) {
+            try {
+                const watcher = validateWatcherDefinition(rawWatcher);
+                assertHostAllowed(this.config, watcher.endpoint);
+                assertWatcherLimits(this.config, this.list(), watcher);
+                this.watchers.set(watcher.id, watcher);
+            }
+            catch (err) {
+                this.runtime[rawWatcher.id] = {
+                    id: rawWatcher.id,
+                    consecutiveFailures: (this.runtime[rawWatcher.id]?.consecutiveFailures ?? 0) + 1,
+                    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,
+                };
+            }
+        }
+        for (const watcher of this.list().filter((w) => w.enabled))
+            await this.startWatcher(watcher.id);
+    }
+    async create(input) {
+        const watcher = validateWatcherDefinition(input);
+        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 };
+        if (watcher.enabled)
+            await this.startWatcher(watcher.id);
+        await this.persist();
+        return watcher;
+    }
+    list() {
+        return [...this.watchers.values()];
+    }
+    status(id) {
+        return this.runtime[id];
+    }
+    async enable(id) {
+        const w = this.require(id);
+        w.enabled = true;
+        await this.startWatcher(id);
+        await this.persist();
+    }
+    async disable(id) {
+        const w = this.require(id);
+        w.enabled = false;
+        await this.stopWatcher(id);
+        await this.persist();
+    }
+    async remove(id) {
+        await this.stopWatcher(id);
+        this.watchers.delete(id);
+        delete this.runtime[id];
+        await this.persist();
+    }
+    require(id) {
+        const w = this.watchers.get(id);
+        if (!w)
+            throw new Error(`Watcher not found: ${id}`);
+        return w;
+    }
+    async startWatcher(id) {
+        if (this.stops.has(id))
+            return;
+        const watcher = this.require(id);
+        const handler = {
+            "http-poll": httpPollStrategy,
+            websocket: websocketStrategy,
+            sse: sseStrategy,
+            "http-long-poll": httpLongPollStrategy,
+        }[watcher.strategy];
+        const handleFailure = async (err) => {
+            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0 };
+            rt.consecutiveFailures += 1;
+            rt.lastError = String(err?.message ?? err);
+            this.runtime[id] = rt;
+            if (this.retryTimers.has(id)) {
+                await this.persist();
+                return;
+            }
+            const delay = backoff(watcher.retry.baseMs, watcher.retry.maxMs, rt.consecutiveFailures);
+            if (rt.consecutiveFailures <= watcher.retry.maxRetries && watcher.enabled) {
+                await this.stopWatcher(id);
+                const timer = setTimeout(() => {
+                    this.retryTimers.delete(id);
+                    this.startWatcher(id).catch(() => undefined);
+                }, delay);
+                this.retryTimers.set(id, timer);
+            }
+            await this.persist();
+        };
+        const stop = await handler(watcher, async (payload) => {
+            const rt = this.runtime[id] ?? { id, consecutiveFailures: 0 };
+            const previousPayload = rt.lastPayload;
+            const matched = evaluateConditions(watcher.conditions, watcher.match, payload, previousPayload);
+            rt.lastPayloadHash = hashPayload(payload);
+            rt.lastPayload = payload;
+            rt.lastResponseAt = new Date().toISOString();
+            rt.lastEvaluated = rt.lastResponseAt;
+            rt.consecutiveFailures = 0;
+            rt.lastError = undefined;
+            this.runtime[id] = rt;
+            if (matched) {
+                const body = renderTemplate(watcher.fire.payloadTemplate, {
+                    watcher,
+                    event: { name: watcher.fire.eventName },
+                    payload,
+                    timestamp: new Date().toISOString(),
+                });
+                await this.dispatcher.dispatch(watcher.fire.webhookPath, body);
+                if (watcher.fireOnce) {
+                    watcher.enabled = false;
+                    await this.stopWatcher(id);
+                }
+            }
+            await this.persist();
+        }, handleFailure);
+        this.stops.set(id, stop);
+    }
+    async stopWatcher(id) {
+        const timer = this.retryTimers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.retryTimers.delete(id);
+        }
+        const stop = this.stops.get(id);
+        if (stop)
+            await Promise.resolve(stop());
+        this.stops.delete(id);
+    }
+    async audit() {
+        const bySkill = this.list().reduce((acc, w) => {
+            acc[w.skillId] = (acc[w.skillId] ?? 0) + 1;
+            return acc;
+        }, {});
+        return {
+            totals: {
+                watchers: this.list().length,
+                enabled: this.list().filter((w) => w.enabled).length,
+                errored: Object.values(this.runtime).filter((r) => !!r.lastError).length,
+            },
+            bySkill,
+            allowedHosts: this.config.allowedHosts,
+            limits: this.config.limits,
+            statePath: this.statePath,
+        };
+    }
+    async persist() {
+        await saveState(this.statePath, this.list(), this.runtime);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeexdev/openclaw-sentinel",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",
@@ -36,7 +36,8 @@
     "format:check": "oxfmt --check .",
     "changeset": "changeset",
     "version-packages": "changeset version",
-    "release": "changeset publish"
+    "release": "changeset publish",
+    "prepack": "npm run build"
   },
   "dependencies": {
     "re2-wasm": "^1.0.2",
@@ -56,5 +57,10 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
   }
 }