@vainplex/openclaw-governance 0.1.0

package/dist/src/types.js

@@ -0,0 +1,3 @@
+// ── OpenClaw Plugin API (external contract, do not modify) ──
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,+DAA+D"}

package/dist/src/util.d.ts

@@ -0,0 +1,28 @@
+import type { TimeContext, TrustTier } from "./types.js";
+/** Parse "HH:MM" to minutes since midnight */
+export declare function parseTimeToMinutes(time: string): number;
+/** Check if currentMinutes is within the range [after, before), handling midnight wrap */
+export declare function isInTimeRange(currentMinutes: number, afterMinutes: number, beforeMinutes: number): boolean;
+/** Get current time context for a timezone */
+export declare function getCurrentTime(timezone: string): TimeContext;
+/** Convert a glob pattern to a RegExp (supports * and ?) */
+export declare function globToRegex(pattern: string): RegExp;
+/** SHA-256 hash of a string */
+export declare function sha256(data: string): string;
+/** Clamp a value between min and max */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Current time in microseconds (from performance.now) */
+export declare function nowUs(): number;
+/** Extract agent ID from session key or explicit agentId */
+export declare function extractAgentId(sessionKey?: string, agentId?: string): string;
+/** Check if a session key indicates a sub-agent */
+export declare function isSubAgent(sessionKey?: string): boolean;
+/** Extract parent session key from a sub-agent session key.
+ *  "agent:main:subagent:forge:abc" → "agent:main"
+ *  Returns null for root agents. */
+export declare function extractParentSessionKey(sessionKey: string): string | null;
+/** Map trust score to tier */
+export declare function scoreToTier(score: number): TrustTier;
+/** Map trust tier to its ordinal for comparisons */
+export declare function tierOrdinal(tier: TrustTier): number;
+//# sourceMappingURL=util.d.ts.map

package/dist/src/util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAC3B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,MAAM,GACpB,OAAO,CAMT;AAED,8CAA8C;AAC9C,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAoC5D;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,+BAA+B;AAC/B,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,wCAAwC;AACxC,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,0DAA0D;AAC1D,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED,4DAA4D;AAC5D,wBAAgB,cAAc,CAC5B,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAWR;AAED,mDAAmD;AACnD,wBAAgB,UAAU,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;oCAEoC;AACpC,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,IAAI,CAIf;AAED,8BAA8B;AAC9B,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAMpD;AAED,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CASnD"}

package/dist/src/util.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+/** Parse "HH:MM" to minutes since midnight */
+export function parseTimeToMinutes(time) {
+    const parts = time.split(":");
+    const h = Number(parts[0]);
+    const m = Number(parts[1]);
+    if (Number.isNaN(h) || Number.isNaN(m) || h < 0 || h > 23 || m < 0 || m > 59) {
+        return -1;
+    }
+    return h * 60 + m;
+}
+/** Check if currentMinutes is within the range [after, before), handling midnight wrap */
+export function isInTimeRange(currentMinutes, afterMinutes, beforeMinutes) {
+    if (afterMinutes <= beforeMinutes) {
+        return currentMinutes >= afterMinutes && currentMinutes < beforeMinutes;
+    }
+    // Midnight wrap: e.g., after=23:00(1380), before=06:00(360)
+    return currentMinutes >= afterMinutes || currentMinutes < beforeMinutes;
+}
+/** Get current time context for a timezone */
+export function getCurrentTime(timezone) {
+    const now = new Date();
+    const formatter = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour: "numeric",
+        minute: "numeric",
+        weekday: "short",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour12: false,
+    });
+    const parts = formatter.formatToParts(now);
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? "0";
+    const hour = Number(get("hour")) % 24;
+    const minute = Number(get("minute"));
+    const year = get("year");
+    const month = get("month");
+    const day = get("day");
+    const dayMap = {
+        Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6,
+    };
+    const weekday = get("weekday");
+    const dayOfWeek = dayMap[weekday] ?? 0;
+    return {
+        hour,
+        minute,
+        dayOfWeek,
+        date: `${year}-${month}-${day}`,
+        timezone,
+    };
+}
+/** Convert a glob pattern to a RegExp (supports * and ?) */
+export function globToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+}
+/** SHA-256 hash of a string */
+export function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+/** Clamp a value between min and max */
+export function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+/** Current time in microseconds (from performance.now) */
+export function nowUs() {
+    return Math.round(performance.now() * 1000);
+}
+/** Extract agent ID from session key or explicit agentId */
+export function extractAgentId(sessionKey, agentId) {
+    if (agentId)
+        return agentId;
+    if (!sessionKey)
+        return "unknown";
+    // "agent:main:subagent:forge:abc123" → "forge"
+    // "agent:main" → "main"
+    const parts = sessionKey.split(":");
+    if (parts.length >= 4 && parts[2] === "subagent") {
+        return parts[3] ?? "unknown";
+    }
+    return parts[1] ?? "unknown";
+}
+/** Check if a session key indicates a sub-agent */
+export function isSubAgent(sessionKey) {
+    if (!sessionKey)
+        return false;
+    return sessionKey.includes(":subagent:");
+}
+/** Extract parent session key from a sub-agent session key.
+ *  "agent:main:subagent:forge:abc" → "agent:main"
+ *  Returns null for root agents. */
+export function extractParentSessionKey(sessionKey) {
+    const idx = sessionKey.indexOf(":subagent:");
+    if (idx === -1)
+        return null;
+    return sessionKey.substring(0, idx);
+}
+/** Map trust score to tier */
+export function scoreToTier(score) {
+    if (score >= 80)
+        return "privileged";
+    if (score >= 60)
+        return "trusted";
+    if (score >= 40)
+        return "standard";
+    if (score >= 20)
+        return "restricted";
+    return "untrusted";
+}
+/** Map trust tier to its ordinal for comparisons */
+export function tierOrdinal(tier) {
+    const map = {
+        untrusted: 0,
+        restricted: 1,
+        standard: 2,
+        trusted: 3,
+        privileged: 4,
+    };
+    return map[tier];
+}
+//# sourceMappingURL=util.js.map

package/dist/src/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../src/util.ts"],"names":[],"mappings":"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"}

package/openclaw.plugin.json

@@ -0,0 +1,87 @@
+{
+  "id": "openclaw-governance",
+  "name": "OpenClaw Governance",
+  "description": "Contextual, learning, cross-agent governance for AI agents",
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable/disable the governance engine"
+      },
+      "timezone": {
+        "type": "string",
+        "default": "UTC",
+        "description": "Timezone for time-aware policies (IANA format)"
+      },
+      "failMode": {
+        "type": "string",
+        "enum": ["open", "closed"],
+        "default": "open",
+        "description": "Behavior on engine errors: open (allow) or closed (deny)"
+      },
+      "policies": {
+        "type": "array",
+        "default": [],
+        "description": "Policy definitions"
+      },
+      "timeWindows": {
+        "type": "object",
+        "default": {},
+        "description": "Named time windows for time conditions"
+      },
+      "trust": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "defaults": { "type": "object", "default": { "main": 60, "*": 10 } },
+          "persistIntervalSeconds": { "type": "number", "default": 60 },
+          "decay": {
+            "type": "object",
+            "properties": {
+              "enabled": { "type": "boolean", "default": true },
+              "inactivityDays": { "type": "number", "default": 30 },
+              "rate": { "type": "number", "default": 0.95 }
+            }
+          },
+          "weights": { "type": "object" },
+          "maxHistoryPerAgent": { "type": "number", "default": 100 }
+        }
+      },
+      "audit": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean", "default": true },
+          "retentionDays": { "type": "number", "default": 90 },
+          "redactPatterns": { "type": "array", "items": { "type": "string" }, "default": [] },
+          "level": { "type": "string", "enum": ["minimal", "standard", "verbose"], "default": "standard" }
+        }
+      },
+      "toolRiskOverrides": {
+        "type": "object",
+        "additionalProperties": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "description": "Tool sensitivity overrides (tool name → risk score 0-100)"
+      },
+      "builtinPolicies": {
+        "type": "object",
+        "properties": {
+          "nightMode": {},
+          "credentialGuard": { "type": "boolean" },
+          "productionSafeguard": { "type": "boolean" },
+          "rateLimiter": {}
+        }
+      },
+      "performance": {
+        "type": "object",
+        "properties": {
+          "maxEvalUs": { "type": "number", "default": 5000 },
+          "maxContextMessages": { "type": "number", "default": 10 },
+          "frequencyBufferSize": { "type": "number", "default": 1000 }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vainplex/openclaw-governance",
+  "version": "0.1.0",
+  "description": "Contextual, learning, cross-agent governance for AI agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist/"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@vitest/coverage-v8": "^3.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "author": "Albert Hild <albert@vainplex.dev>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alberthild/openclaw-governance.git"
+  },
+  "keywords": [
+    "openclaw",
+    "governance",
+    "ai-agents",
+    "policy-engine",
+    "trust",
+    "audit"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}