@coffeexdev/openclaw-sentinel 0.1.3 → 0.1.5

package/README.md

@@ -47,6 +47,8 @@ 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";
 

package/dist/configSchema.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
+export declare const sentinelConfigSchema: OpenClawPluginConfigSchema;

package/dist/configSchema.js

@@ -0,0 +1,115 @@
+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({}),
+});
+export const sentinelConfigSchema = {
+    safeParse: (value) => {
+        if (value === undefined)
+            return { success: true, data: undefined };
+        return configZodSchema.safeParse(value);
+    },
+    jsonSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            allowedHosts: {
+                type: "array",
+                items: { type: "string" },
+                description: "Hostnames the watchers are permitted to connect to. Must be explicitly configured — no hosts are allowed by default.",
+                default: [],
+            },
+            localDispatchBase: {
+                type: "string",
+                format: "uri",
+                description: "Base URL for internal webhook dispatch",
+                default: "http://127.0.0.1:18789",
+            },
+            dispatchAuthToken: {
+                type: "string",
+                description: "Bearer token for authenticating webhook dispatch requests",
+            },
+            stateFilePath: {
+                type: "string",
+                description: "Custom path for the sentinel state persistence file",
+            },
+            limits: {
+                type: "object",
+                additionalProperties: false,
+                description: "Resource limits for watcher creation",
+                properties: {
+                    maxWatchersTotal: {
+                        type: "number",
+                        description: "Maximum total watchers across all skills",
+                        default: 200,
+                    },
+                    maxWatchersPerSkill: {
+                        type: "number",
+                        description: "Maximum watchers per skill",
+                        default: 20,
+                    },
+                    maxConditionsPerWatcher: {
+                        type: "number",
+                        description: "Maximum conditions per watcher definition",
+                        default: 25,
+                    },
+                    maxIntervalMsFloor: {
+                        type: "number",
+                        description: "Minimum allowed polling interval in milliseconds",
+                        default: 1000,
+                    },
+                },
+            },
+        },
+    },
+    uiHints: {
+        allowedHosts: {
+            label: "Allowed Hosts",
+            help: "Hostnames the watchers are permitted to connect to",
+        },
+        localDispatchBase: {
+            label: "Dispatch Base URL",
+            help: "Base URL for internal webhook dispatch (default: http://127.0.0.1:18789)",
+        },
+        dispatchAuthToken: {
+            label: "Dispatch Auth Token",
+            help: "Bearer token for webhook dispatch authentication (or use SENTINEL_DISPATCH_TOKEN env var)",
+            sensitive: true,
+            placeholder: "sk-...",
+        },
+        stateFilePath: {
+            label: "State File Path",
+            help: "Custom path for sentinel state persistence file",
+            advanced: true,
+        },
+        "limits.maxWatchersTotal": {
+            label: "Max Watchers",
+            help: "Maximum total watchers across all skills",
+            advanced: true,
+        },
+        "limits.maxWatchersPerSkill": {
+            label: "Max Per Skill",
+            help: "Maximum watchers a single skill can create",
+            advanced: true,
+        },
+        "limits.maxConditionsPerWatcher": {
+            label: "Max Conditions",
+            help: "Maximum conditions per watcher definition",
+            advanced: true,
+        },
+        "limits.maxIntervalMsFloor": {
+            label: "Min Poll Interval (ms)",
+            help: "Minimum allowed polling interval in milliseconds",
+            advanced: true,
+        },
+    },
+};

package/dist/index.d.ts

@@ -1,10 +1,19 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 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;
+    register(api: OpenClawPluginApi): void;
 };
+declare const sentinelPlugin: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register(api: OpenClawPluginApi): void;
+};
+export declare const register: (api: OpenClawPluginApi) => void;
+export declare const activate: (api: OpenClawPluginApi) => void;
+export default sentinelPlugin;
 export * from "./types.js";

package/dist/index.js

@@ -1,8 +1,9 @@
 import { registerSentinelControl } from "./tool.js";
 import { WatcherManager } from "./watcherManager.js";
+import { sentinelConfigSchema } from "./configSchema.js";
 export function createSentinelPlugin(overrides) {
     const config = {
-        allowedHosts: ["api.github.com", "api.coingecko.com", "example.com"],
+        allowedHosts: [],
         localDispatchBase: "http://127.0.0.1:18789",
         dispatchAuthToken: process.env.SENTINEL_DISPATCH_TOKEN,
         limits: {
@@ -31,8 +32,23 @@ export function createSentinelPlugin(overrides) {
             await manager.init();
         },
         register(api) {
-            registerSentinelControl(api.registerTool, manager);
+            registerSentinelControl(api.registerTool.bind(api), manager);
         },
     };
 }
+// OpenClaw plugin entrypoint (default plugin object with register)
+const sentinelPlugin = {
+    id: "openclaw-sentinel",
+    name: "OpenClaw Sentinel",
+    description: "Secure declarative gateway-native watcher plugin for OpenClaw",
+    configSchema: sentinelConfigSchema,
+    register(api) {
+        const plugin = createSentinelPlugin(api.pluginConfig);
+        void plugin.init();
+        plugin.register(api);
+    },
+};
+export const register = sentinelPlugin.register.bind(sentinelPlugin);
+export const activate = sentinelPlugin.register.bind(sentinelPlugin);
+export default sentinelPlugin;
 export * from "./types.js";

package/dist/tool.d.ts

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

package/dist/tool.js

@@ -1,5 +1,7 @@
+import { jsonResult } from "openclaw/plugin-sdk";
 import { z } from "zod";
-const inputSchema = z
+import { SentinelToolSchema } from "./toolSchema.js";
+const ParamsSchema = z
     .object({
     action: z.enum(["create", "enable", "disable", "remove", "status", "list"]),
     id: z.string().optional(),
@@ -7,32 +9,27 @@ const inputSchema = z
 })
     .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();
-        }
+    registerTool({
+        name: "sentinel_control",
+        label: "sentinel_control",
+        description: "Create/manage sentinel watchers",
+        parameters: SentinelToolSchema,
+        async execute(_toolCallId, params) {
+            const payload = ParamsSchema.parse((params ?? {}));
+            switch (payload.action) {
+                case "create":
+                    return jsonResult(await manager.create(payload.watcher));
+                case "enable":
+                    return jsonResult(await manager.enable(payload.id ?? ""));
+                case "disable":
+                    return jsonResult(await manager.disable(payload.id ?? ""));
+                case "remove":
+                    return jsonResult(await manager.remove(payload.id ?? ""));
+                case "status":
+                    return jsonResult(manager.status(payload.id ?? ""));
+                case "list":
+                    return jsonResult(manager.list());
+            }
+        },
     });
 }

package/dist/toolSchema.d.ts

@@ -0,0 +1,34 @@
+export declare const SentinelToolSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"enable">, import("@sinclair/typebox").TLiteral<"disable">, import("@sinclair/typebox").TLiteral<"remove">, import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"list">]>;
+    id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    watcher: import("@sinclair/typebox").TOptional<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").TNumber>;
+        timeoutMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        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").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]>>;
+        }>;
+        retry: import("@sinclair/typebox").TObject<{
+            maxRetries: import("@sinclair/typebox").TNumber;
+            baseMs: import("@sinclair/typebox").TNumber;
+            maxMs: import("@sinclair/typebox").TNumber;
+        }>;
+        fireOnce: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        metadata: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
+    }>>;
+}>;

package/dist/toolSchema.js

@@ -0,0 +1,77 @@
+import { Type } from "@sinclair/typebox";
+const ConditionSchema = Type.Object({
+    path: Type.String({ description: "JSONPath expression to evaluate against the response" }),
+    op: Type.Union([
+        Type.Literal("eq"),
+        Type.Literal("neq"),
+        Type.Literal("gt"),
+        Type.Literal("gte"),
+        Type.Literal("lt"),
+        Type.Literal("lte"),
+        Type.Literal("exists"),
+        Type.Literal("absent"),
+        Type.Literal("contains"),
+        Type.Literal("matches"),
+        Type.Literal("changed"),
+    ], { description: "Comparison operator" }),
+    value: Type.Optional(Type.Unknown({
+        description: "Value to compare against (not needed for exists/absent/changed)",
+    })),
+});
+const FireConfigSchema = Type.Object({
+    webhookPath: Type.String({
+        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()]), {
+        description: "Key-value template for the webhook payload. Supports {{mustache}} interpolation from matched response data.",
+    }),
+});
+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 WatcherSchema = Type.Object({
+    id: Type.String({ description: "Unique watcher identifier" }),
+    skillId: Type.String({ description: "ID of the skill that owns this watcher" }),
+    enabled: Type.Boolean({ description: "Whether the watcher is actively polling" }),
+    strategy: Type.Union([
+        Type.Literal("http-poll"),
+        Type.Literal("websocket"),
+        Type.Literal("sse"),
+        Type.Literal("http-long-poll"),
+    ], { description: "Connection strategy" }),
+    endpoint: Type.String({ description: "URL to monitor" }),
+    method: Type.Optional(Type.Union([Type.Literal("GET"), Type.Literal("POST")], {
+        description: "HTTP method (default GET)",
+    })),
+    headers: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: "HTTP headers to include in requests",
+    })),
+    body: Type.Optional(Type.String({ description: "Request body for POST requests" })),
+    intervalMs: Type.Optional(Type.Number({ description: "Polling interval in milliseconds" })),
+    timeoutMs: Type.Optional(Type.Number({ description: "Request timeout in milliseconds" })),
+    match: Type.Union([Type.Literal("all"), Type.Literal("any")], {
+        description: "Whether all or any conditions must match to trigger",
+    }),
+    conditions: Type.Array(ConditionSchema, {
+        description: "Conditions evaluated against each response",
+    }),
+    fire: FireConfigSchema,
+    retry: RetryPolicySchema,
+    fireOnce: Type.Optional(Type.Boolean({ description: "If true, the watcher disables itself after firing once" })),
+    metadata: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Arbitrary key-value metadata" })),
+}, { description: "Full watcher definition" });
+export const SentinelToolSchema = Type.Object({
+    action: Type.Union([
+        Type.Literal("create"),
+        Type.Literal("enable"),
+        Type.Literal("disable"),
+        Type.Literal("remove"),
+        Type.Literal("status"),
+        Type.Literal("list"),
+    ], { description: "The action to perform" }),
+    id: Type.Optional(Type.String({ description: "Watcher ID (required for enable/disable/remove/status)" })),
+    watcher: Type.Optional(WatcherSchema),
+});

package/openclaw.plugin.json

@@ -2,8 +2,97 @@
   "id": "openclaw-sentinel",
   "configSchema": {
     "type": "object",
-    "additionalProperties": true,
-    "properties": {}
+    "additionalProperties": false,
+    "properties": {
+      "allowedHosts": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Hostnames the watchers are permitted to connect to. Must be explicitly configured — no hosts are allowed by default.",
+        "default": []
+      },
+      "localDispatchBase": {
+        "type": "string",
+        "format": "uri",
+        "description": "Base URL for internal webhook dispatch",
+        "default": "http://127.0.0.1:18789"
+      },
+      "dispatchAuthToken": {
+        "type": "string",
+        "description": "Bearer token for authenticating webhook dispatch requests"
+      },
+      "stateFilePath": {
+        "type": "string",
+        "description": "Custom path for the sentinel state persistence file"
+      },
+      "limits": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "Resource limits for watcher creation",
+        "properties": {
+          "maxWatchersTotal": {
+            "type": "number",
+            "description": "Maximum total watchers across all skills",
+            "default": 200
+          },
+          "maxWatchersPerSkill": {
+            "type": "number",
+            "description": "Maximum watchers per skill",
+            "default": 20
+          },
+          "maxConditionsPerWatcher": {
+            "type": "number",
+            "description": "Maximum conditions per watcher definition",
+            "default": 25
+          },
+          "maxIntervalMsFloor": {
+            "type": "number",
+            "description": "Minimum allowed polling interval in milliseconds",
+            "default": 1000
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "allowedHosts": {
+      "label": "Allowed Hosts",
+      "help": "Hostnames the watchers are permitted to connect to"
+    },
+    "localDispatchBase": {
+      "label": "Dispatch Base URL",
+      "help": "Base URL for internal webhook dispatch"
+    },
+    "dispatchAuthToken": {
+      "label": "Dispatch Auth Token",
+      "help": "Bearer token for webhook dispatch authentication",
+      "sensitive": true,
+      "placeholder": "sk-..."
+    },
+    "stateFilePath": {
+      "label": "State File Path",
+      "help": "Custom path for sentinel state persistence file",
+      "advanced": true
+    },
+    "limits.maxWatchersTotal": {
+      "label": "Max Watchers",
+      "help": "Maximum total watchers across all skills",
+      "advanced": true
+    },
+    "limits.maxWatchersPerSkill": {
+      "label": "Max Per Skill",
+      "help": "Maximum watchers a single skill can create",
+      "advanced": true
+    },
+    "limits.maxConditionsPerWatcher": {
+      "label": "Max Conditions",
+      "help": "Maximum conditions per watcher definition",
+      "advanced": true
+    },
+    "limits.maxIntervalMsFloor": {
+      "label": "Min Poll Interval (ms)",
+      "help": "Minimum allowed polling interval in milliseconds",
+      "advanced": true
+    }
   },
   "install": {
     "npmSpec": "@coffeexdev/openclaw-sentinel"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffeexdev/openclaw-sentinel",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Secure declarative gateway-native watcher plugin for OpenClaw",
   "keywords": [
     "openclaw",
@@ -38,9 +38,11 @@
     "changeset": "changeset",
     "version-packages": "changeset version",
     "release": "changeset publish",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "prepare": "husky"
   },
   "dependencies": {
+    "@sinclair/typebox": "^0.34.48",
     "re2-wasm": "^1.0.2",
     "ws": "^8.18.3",
     "zod": "^3.24.1"
@@ -49,15 +51,24 @@
     "@changesets/cli": "^2.29.7",
     "@types/node": "^24.0.0",
     "@types/ws": "^8.5.13",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "openclaw": "latest",
     "oxfmt": "^0.36.0",
     "typescript": "^5.8.2",
     "vitest": "^3.0.8"
   },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.2"
+  },
   "optionalDependencies": {
     "re2": "^1.23.3"
   },
+  "lint-staged": {
+    "*.{ts,js,jsx,tsx,mjs,cjs,json,yml,yaml,md,css,html}": "oxfmt --write"
+  },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "openclaw": {
     "extensions": [