openclaw-zero-agency 0.2.0 → 0.2.1

package/dist/gate.js

@@ -13,7 +13,7 @@ async function telemetry(path, record) {
     catch { /* never break a turn */ }
 }
 export default definePluginEntry({
-    id: "zero-agency-gate",
+    id: "zero-agency/gate",
     name: "Zero Agency Gate",
     description: "Requires a Zero Agency routing receipt before consequential tool calls.",
     register(api) {

package/dist/index.js

@@ -0,0 +1,157 @@
+// Zero Agency — single-entry plugin: capability routing tools + receipt gate.
+// Packs inform judgement; they never confer authority.
+//
+// NOTE: kept as one entry on purpose. A hook-bearing plugin cannot pass
+// `openclaw plugins validate` (it requires defineToolPlugin metadata), and a
+// multi-entry package cannot satisfy the manifest-id check. Runtime load is the
+// authoritative test for this package.
+import { Type } from "typebox";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { readFile, appendFile, mkdir } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+const KEY = "openclaw.zero-agency.receipts.v1";
+function store() {
+    const g = globalThis;
+    if (!g[KEY])
+        g[KEY] = new Map();
+    return g[KEY];
+}
+const prune = () => { const t = Date.now(); for (const [k, v] of store())
+    if (v.expires < t)
+        store().delete(k); };
+const cache = new Map();
+const norm = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9\s-]/g, " ").replace(/\s+/g, " ").trim();
+async function loadRegistry(path) {
+    const st = statSync(path);
+    const hit = cache.get(path);
+    if (hit && hit.mtimeMs === st.mtimeMs)
+        return hit.data;
+    const data = JSON.parse(await readFile(path, "utf8"));
+    cache.set(path, { mtimeMs: st.mtimeMs, data });
+    return data;
+}
+function score(cap, q) {
+    let s = 0;
+    const hits = [];
+    for (const t of cap.triggers ?? []) {
+        const nt = norm(t);
+        if (nt && q.includes(nt)) {
+            s += 3;
+            hits.push(t);
+            continue;
+        }
+        const words = nt.split(" ").filter((w) => w.length > 3);
+        const overlap = words.filter((w) => q.includes(w)).length;
+        if (words.length && overlap === words.length) {
+            s += 2;
+            hits.push(t);
+        }
+        else if (overlap)
+            s += overlap / words.length;
+    }
+    const dw = norm(cap.description).split(" ").filter((w) => w.length > 4);
+    s += 0.5 * dw.filter((w) => q.includes(w)).length;
+    return { score: s, hits };
+}
+async function telemetry(path, record) {
+    if (!path)
+        return;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, JSON.stringify({ ts: new Date().toISOString(), ...record }) + "\n");
+    }
+    catch { /* telemetry must never break a turn */ }
+}
+export default definePluginEntry({
+    id: "zero-agency",
+    name: "Zero Agency",
+    description: "Capability routing with a receipt gate. Packs inform judgement; they never confer authority.",
+    register(api) {
+        const cfg = api.config ?? api.pluginConfig ?? {};
+        const registryPath = cfg.registryPath ?? "";
+        const telemetryPath = cfg.telemetryPath;
+        const gateMode = cfg.gateMode ?? "advisory";
+        const consequential = cfg.consequentialTools ?? ["exec", "apply_patch"];
+        const ttl = cfg.receiptTtlMs ?? 900000;
+        api.registerTool({
+            name: "zero_agency_route",
+            description: "Find the capability pack governing a domain task. Call before acting on security review, release verification or incident triage. Issues a receipt the gate accepts.",
+            parameters: Type.Object({
+                task: Type.String({ description: "The task or question, in natural language." }),
+                limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 5 })),
+            }),
+            outputSchema: Type.Object({
+                candidates: Type.Array(Type.Object({ id: Type.String(), pack: Type.String(), score: Type.Number(), triggers: Type.Array(Type.String()) })),
+                receipt: Type.Union([Type.String(), Type.Null()]),
+                note: Type.String(),
+            }, { additionalProperties: false }),
+            async execute(_id, params, ctx) {
+                const q = norm(params.task);
+                let candidates = [];
+                let note = "";
+                try {
+                    const reg = await loadRegistry(registryPath);
+                    candidates = (reg.capabilities ?? [])
+                        .map((c) => ({ c, ...score(c, q) }))
+                        .filter((x) => x.score > 0)
+                        .sort((a, b) => b.score - a.score)
+                        .slice(0, params.limit ?? 3)
+                        .map((x) => ({ id: x.c.id, pack: x.c.pack, score: Number(x.score.toFixed(2)), triggers: x.hits }));
+                    note = candidates.length ? `load ${candidates[0].pack} before acting` : "no capability matched; if this action is consequential, stop and ask";
+                }
+                catch (e) {
+                    note = `registry unavailable: ${e?.message ?? "unknown"}`;
+                }
+                let receipt = null;
+                if (candidates.length) {
+                    const runId = ctx?.runId ?? ctx?.sessionId ?? "unknown-run";
+                    receipt = createHash("sha256").update(`${runId}:${candidates[0].id}:${Date.now()}:${randomUUID()}`).digest("hex").slice(0, 16);
+                    store().set(runId, { id: receipt, pack: candidates[0].pack, at: Date.now(), expires: Date.now() + ttl });
+                    prune();
+                }
+                await telemetry(telemetryPath, { kind: "route", agent: ctx?.agentId ?? null, session: ctx?.sessionKey ?? null, query: params.task.slice(0, 200), selected: candidates[0]?.id ?? null, candidates: candidates.length, receipt });
+                return { content: [{ type: "text", text: JSON.stringify({ candidates, receipt, note }) }], details: { candidates, receipt, note } };
+            },
+        });
+        api.registerTool({
+            name: "zero_agency_status",
+            description: "Report Zero Agency registry state: capability count, token total and live receipts.",
+            parameters: Type.Object({}),
+            outputSchema: Type.Object({ registry: Type.String(), capabilities: Type.Integer(), tokens: Type.Integer(), receipts: Type.Integer(), registryError: Type.Union([Type.String(), Type.Null()]) }, { additionalProperties: false }),
+            async execute() {
+                try {
+                    const reg = await loadRegistry(registryPath);
+                    const caps = reg.capabilities ?? [];
+                    return { content: [{ type: "text", text: `zero-agency: ${caps.length} capabilities` }], details: { registry: registryPath, capabilities: caps.length, tokens: caps.reduce((s, c) => s + (c.tokens ?? 0), 0), receipts: store().size, registryError: null } };
+                }
+                catch (e) {
+                    return { content: [{ type: "text", text: `zero-agency: registry error` }], details: { registry: registryPath, capabilities: 0, tokens: 0, receipts: store().size, registryError: e?.message ?? "unknown" } };
+                }
+            },
+        });
+        api.on("before_tool_call", async (event, ctx) => {
+            if (gateMode === "off")
+                return undefined;
+            const runId = event?.runId ?? ctx?.runId ?? "unknown-run";
+            prune();
+            const r = store().get(runId);
+            if (r) {
+                await telemetry(telemetryPath, { kind: "gate", decision: "receipt-ok", tool: event?.toolName, runId, receipt: r.id });
+                return undefined;
+            }
+            await telemetry(telemetryPath, { kind: "gate", decision: gateMode === "enforce" ? "blocked" : "advisory-miss", tool: event?.toolName, runId });
+            if (gateMode !== "enforce")
+                return undefined;
+            return {
+                requireApproval: {
+                    title: `Zero Agency: no capability receipt (${event?.toolName ?? "tool"})`,
+                    description: "Consequential call without a capability lookup. Approve for this call only, or deny and run zero_agency_route first.",
+                    severity: "warning", timeoutMs: 120000, allowedDecisions: ["allow-once", "deny"],
+                    onResolution: async (decision) => { await telemetry(telemetryPath, { kind: "gate", decision, tool: event?.toolName, runId, receipt: null }); },
+                },
+            };
+        }, { matcher: consequential, priority: 50 });
+    },
+});

package/dist/tools.js

@@ -50,7 +50,7 @@ async function telemetry(path, record) {
     catch { /* telemetry must never break a turn */ }
 }
 export default defineToolPlugin({
-    id: "zero-agency",
+    id: "zero-agency/tools",
     name: "Zero Agency",
     description: "Capability routing for the fleet. Packs inform judgement; they never confer authority.",
     configSchema: Type.Object({

package/openclaw.plugin.json

@@ -1,59 +1,19 @@
 {
   "id": "zero-agency",
   "name": "Zero Agency",
-  "description": "Capability routing for the fleet. Packs inform judgement; they never confer authority.",
-  "activation": {
-    "onStartup": true
-  },
+  "description": "Capability routing with a receipt gate. Packs inform judgement; they never confer authority.",
+  "activation": { "onStartup": true },
+  "contracts": { "tools": ["zero_agency_route", "zero_agency_status"] },
   "configSchema": {
     "type": "object",
-    "required": [
-      "registryPath"
-    ],
+    "additionalProperties": false,
+    "required": ["registryPath"],
     "properties": {
-      "registryPath": {
-        "type": "string",
-        "description": "Absolute path to capabilities.json (read-only)."
-      },
-      "telemetryPath": {
-        "type": "string",
-        "description": "JSONL telemetry path."
-      },
-      "receiptTtlMs": {
-        "type": "integer",
-        "minimum": 1000
-      },
-      "gateMode": {
-        "anyOf": [
-          {
-            "type": "string",
-            "const": "off"
-          },
-          {
-            "type": "string",
-            "const": "advisory"
-          },
-          {
-            "type": "string",
-            "const": "enforce"
-          }
-        ],
-        "description": "Receipt gate mode (default advisory)."
-      },
-      "consequentialTools": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        },
-        "description": "Tool ids gated by receipt."
-      }
+      "registryPath": { "type": "string", "description": "Absolute path to capabilities.json (read-only)." },
+      "telemetryPath": { "type": "string", "description": "JSONL telemetry path." },
+      "receiptTtlMs": { "type": "integer", "minimum": 1000, "default": 900000 },
+      "gateMode": { "type": "string", "enum": ["off", "advisory", "enforce"], "default": "advisory" },
+      "consequentialTools": { "type": "array", "items": { "type": "string" }, "default": ["exec", "apply_patch"] }
     }
-  },
-  "version": "0.2.0",
-  "contracts": {
-    "tools": [
-      "zero_agency_route",
-      "zero_agency_status"
-    ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-zero-agency",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Zero Agency: capability packs, programmatic routing and a receipt gate for OpenClaw. Packs inform judgement; they never confer authority.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,8 +35,7 @@
   },
   "openclaw": {
     "extensions": [
-      "./dist/tools.js",
-      "./dist/gate.js"
+      "./dist/index.js"
     ],
     "compat": {
       "pluginApi": ">=2026.10.1",