openclaw-zero-agency 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apurva Sukant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# openclaw-zero-agency
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Capability routing and a receipt gate for OpenClaw fleets.
+
+**Packs inform judgement; they never confer authority.**
+
+- `zero_agency_route` — match a task to a capability pack, issue a receipt
+- `zero_agency_status` — registry version, capability count, gate mode
+- `before_tool_call` gate — consequential tools require a receipt
+
+## Install
+
+```bash
+openclaw plugins install openclaw-zero-agency
+```
+
+## Configure
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "zero-agency": {
+        "config": {
+          "registryPath": "/opt/zero-agency/registry/capabilities.json",
+          "telemetryPath": "/var/log/zero-agency/events.jsonl",
+          "gateMode": "advisory",
+          "consequentialTools": ["exec", "apply_patch"]
+        }
+      }
+    }
+  }
+}
+```
+
+`gateMode`: `off` | `advisory` (log only) | `enforce` (require approval, fail-closed).
+
+Requires `openclaw >= 2026.10.1`.

package/dist/index.js

@@ -0,0 +1,186 @@
+// Zero Agency — capability routing, receipt gate, telemetry.
+// Packs inform judgement; they never confer authority.
+import { Type } from "typebox";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { readFile, appendFile, mkdir } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+const receipts = new Map(); // runId -> receipt
+const registryCache = new Map();
+const now = () => Date.now();
+const norm = (s) => String(s ?? "").toLowerCase().replace(/[^a-z0-9\s-]/g, " ").replace(/\s+/g, " ").trim();
+async function loadRegistry(path) {
+    const { statSync } = await import("node:fs");
+    const st = statSync(path);
+    const hit = registryCache.get(path);
+    if (hit && hit.mtimeMs === st.mtimeMs)
+        return hit.data;
+    const data = JSON.parse(await readFile(path, "utf8"));
+    registryCache.set(path, { mtimeMs: st.mtimeMs, data });
+    return data;
+}
+function scoreCapability(cap, q) {
+    let score = 0;
+    const hits = [];
+    for (const t of cap.triggers ?? []) {
+        const nt = norm(t);
+        if (nt && q.includes(nt)) {
+            score += 3;
+            hits.push(t);
+        }
+        else if (nt) {
+            const words = nt.split(" ").filter((w) => w.length > 3);
+            const overlap = words.filter((w) => q.includes(w)).length;
+            if (words.length && overlap === words.length) {
+                score += 2;
+                hits.push(t);
+            }
+            else if (overlap > 0) {
+                score += overlap / words.length;
+            }
+        }
+    }
+    const descWords = norm(cap.description).split(" ").filter((w) => w.length > 4);
+    score += 0.5 * descWords.filter((w) => q.includes(w)).length;
+    return { score, hits };
+}
+async function writeTelemetry(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 */ }
+}
+function prune(ttl) {
+    const t = now();
+    for (const [k, v] of receipts)
+        if (v.expires < t)
+            receipts.delete(k);
+}
+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 consequentialTools = cfg.consequentialTools ?? ["exec", "apply_patch"];
+        const ttl = cfg.receiptTtlMs ?? 15 * 60 * 1000;
+        api.registerTool({
+            name: "zero_agency_route",
+            description: "Find the Zero Agency capability pack that governs a domain task. Call before acting on security review, release verification, or incident triage. Returns a receipt required by the gate.",
+            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);
+                const limit = params.limit ?? 3;
+                let candidates = [];
+                let note = "";
+                if (!registryPath) {
+                    note = "zero-agency is not configured: registryPath is unset";
+                }
+                else {
+                    try {
+                        const reg = await loadRegistry(registryPath);
+                        candidates = (reg.capabilities ?? [])
+                            .map((c) => ({ c, ...scoreCapability(c, q) }))
+                            .filter((x) => x.score > 0)
+                            .sort((a, b) => b.score - a.score)
+                            .slice(0, limit)
+                            .map((x) => ({ id: x.c.id, pack: x.c.pack, score: Number(x.score.toFixed(2)), triggers: x.hits }));
+                        if (!candidates.length)
+                            note = "no capability matched; if this action is consequential, stop and ask";
+                        else
+                            note = `load ${candidates[0].pack} before acting`;
+                    }
+                    catch (e) {
+                        note = `registry unavailable: ${e.message}`;
+                    }
+                }
+                let receipt = null;
+                if (candidates.length) {
+                    const runId = ctx?.runId ?? "unknown-run";
+                    receipt = createHash("sha256").update(`${runId}:${candidates[0].id}:${now()}:${randomUUID()}`).digest("hex").slice(0, 16);
+                    receipts.set(runId, { id: receipt, pack: candidates[0].pack, at: now(), expires: now() + ttl });
+                    prune(ttl);
+                }
+                await writeTelemetry(telemetryPath, {
+                    kind: "route", runId: ctx?.runId ?? null, 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 version, capability count and gate mode.",
+            parameters: Type.Object({}),
+            outputSchema: Type.Object({
+                gateMode: Type.String(), registry: Type.String(), capabilities: Type.Integer(),
+                receipts: Type.Integer(), registryError: Type.Union([Type.String(), Type.Null()]),
+            }, { additionalProperties: false }),
+            async execute() {
+                let capabilities = 0;
+                let registryError = null;
+                try {
+                    const reg = await loadRegistry(registryPath);
+                    capabilities = (reg.capabilities ?? []).length;
+                }
+                catch (e) {
+                    registryError = e.message;
+                }
+                return {
+                    content: [{ type: "text", text: `zero-agency: ${capabilities} capabilities, gate=${gateMode}` }],
+                    details: { gateMode, registry: registryPath, capabilities, receipts: receipts.size, registryError },
+                };
+            },
+        });
+        // Receipt gate. Fail-closed in enforce mode: no receipt, no consequential call.
+        api.on("before_tool_call", async (event, ctx) => {
+            if (gateMode === "off")
+                return undefined;
+            const runId = event?.runId ?? ctx?.runId ?? "unknown-run";
+            prune(ttl);
+            const r = receipts.get(runId);
+            if (r) {
+                await writeTelemetry(telemetryPath, { kind: "gate", decision: "receipt-ok", tool: event?.toolName, runId, receipt: r.id });
+                return undefined;
+            }
+            await writeTelemetry(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: "This consequential call was made without a capability pack lookup. Approve to proceed for this call only, or deny and run zero_agency_route first.",
+                    severity: "warning",
+                    timeoutMs: 120000,
+                    allowedDecisions: ["allow-once", "deny"],
+                    onResolution: async (decision) => {
+                        await writeTelemetry(telemetryPath, { kind: "gate", decision, tool: event?.toolName, runId, receipt: null });
+                    },
+                },
+            };
+        }, { matcher: consequentialTools, priority: 50 });
+    },
+});

package/openclaw.plugin.json

@@ -0,0 +1,18 @@
+{
+  "id": "zero-agency",
+  "name": "Zero Agency",
+  "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",
+    "additionalProperties": false,
+    "properties": {
+      "registryPath": { "type": "string", "description": "Absolute path to capabilities.json (read-only mount)." },
+      "telemetryPath": { "type": "string", "description": "Absolute path to the JSONL telemetry file." },
+      "gateMode": { "type": "string", "enum": ["off", "advisory", "enforce"], "default": "advisory" },
+      "consequentialTools": { "type": "array", "items": { "type": "string" }, "default": ["exec", "apply_patch"] },
+      "receiptTtlMs": { "type": "integer", "minimum": 1000, "default": 900000 }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "openclaw-zero-agency",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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",
+  "license": "MIT",
+  "keywords": ["openclaw", "openclaw-plugin", "agents", "capability-routing", "governance"],
+  "files": ["dist", "openclaw.plugin.json", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "typebox": "^1.4.3"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^7.0.2"
+  },
+  "openclaw": {
+    "extensions": ["./dist/index.js"],
+    "compat": {
+      "pluginApi": ">=2026.10.1",
+      "minGatewayVersion": "2026.10.1"
+    }
+  }
+}