openclaw-zero-agency 0.2.4 → 1.0.0

package/README.md

@@ -1,12 +1,16 @@
 # openclaw-zero-agency
 
-Capability routing and a receipt gate for OpenClaw fleets.
+Capability routing for OpenClaw agents.
 
 **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
+## What this does
+
+- `zero_agency_route` — match a task to a distilled capability pack and return the pack path
+- `zero_agency_status` — registry state: capability count, token total
+- Routing telemetry — one JSONL line per decision, for measuring routing quality
+
+It does **not** enforce tool permissions. Enforcement belongs to OpenClaw's tool policy and exec approval configuration, which are evaluated by the platform, not by a plugin.
 
 ## Install
 
@@ -23,9 +27,7 @@ openclaw plugins install openclaw-zero-agency
       "zero-agency": {
         "config": {
           "registryPath": "/opt/zero-agency/registry/capabilities.json",
-          "telemetryPath": "/var/log/zero-agency/events.jsonl",
-          "gateMode": "advisory",
-          "consequentialTools": ["exec", "apply_patch"]
+          "telemetryPath": "/var/log/zero-agency/events.jsonl"
         }
       }
     }
@@ -33,6 +35,16 @@ openclaw plugins install openclaw-zero-agency
 }
 ```
 
-`gateMode`: `off` | `advisory` (log only) | `enforce` (require approval, fail-closed).
+`registryPath` is required and must point at a compiled `capabilities.json`.
+
+## The receipt gate is experimental and off by default
+
+`gateMode` exists (`off` | `advisory` | `enforce`) but **`enforce` does not work in the current plugin host**. The `before_tool_call` hook and a tool's `execute` run in separate contexts that share neither memory, run id, nor filesystem — verified across four releases. In `enforce`, every gated call raises an approval prompt because no receipt can ever match.
+
+Leave it `off`. The routing layer is independent of it and is fully functional.
+
+## Provenance
+
+Packs are distilled from pinned upstream sources. Every capability records its source files and commit SHA in frontmatter; the registry is compiled, never hand-edited.
 
 Requires `openclaw >= 2026.10.1`.

package/dist/index.js

@@ -8,7 +8,7 @@
 import { Type } from "typebox";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { readFile, appendFile, mkdir } from "node:fs/promises";
-import { readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { rename, writeFile } from "node:fs/promises";
 import { statSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname } from "node:path";
@@ -26,17 +26,17 @@ const cache = new Map();
 // Receipts are shared through a file, not memory: the tool and the hook run in
 // different execution contexts inside the plugin host, so a Map is not shared.
 let receiptPath = "/tmp/zero-agency-receipts.json";
-function readReceipts() {
+async function readReceipts() {
     try {
-        return JSON.parse(readFileSync(receiptPath, "utf8"));
+        return JSON.parse(await readFile(receiptPath, "utf8"));
     }
     catch {
         return {};
     }
 }
-function writeReceipt(runId, rec) {
+async function writeReceipt(runId, rec) {
     const now = Date.now();
-    const all = readReceipts();
+    const all = await readReceipts();
     for (const k of Object.keys(all)) {
         const v = all[k];
         if (!v || v.expires < now)
@@ -46,15 +46,18 @@ function writeReceipt(runId, rec) {
     if (runId)
         all[runId] = rec;
     try {
-        mkdirSync(dirname(receiptPath), { recursive: true });
+        await mkdir(dirname(receiptPath), { recursive: true });
         const tmp = `${receiptPath}.tmp`;
-        writeFileSync(tmp, JSON.stringify(all));
-        renameSync(tmp, receiptPath);
+        await writeFile(tmp, JSON.stringify(all));
+        await rename(tmp, receiptPath);
+        return true;
+    }
+    catch {
+        return false;
     }
-    catch { /* a missing receipt fails safe */ }
 }
-function findReceipt(runId) {
-    const all = readReceipts();
+async function findReceipt(runId) {
+    const all = await readReceipts();
     const now = Date.now();
     const r = (runId ? all[runId] : undefined) ?? all.global;
     return r && r.expires > now ? r : undefined;
@@ -117,7 +120,7 @@ export default definePluginEntry({
         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.",
+            description: "Find the capability pack governing a domain task. Call before acting on security review, release verification or incident triage. Returns the governing pack and logs the routing decision.",
             parameters: Type.Object({
                 task: Type.String({ description: "The task or question, in natural language." }),
                 limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 5 })),
@@ -148,7 +151,9 @@ export default definePluginEntry({
                 if (candidates.length) {
                     const runId = ctx?.runId ?? ctx?.sessionId ?? null;
                     receipt = createHash("sha256").update(`${runId ?? "global"}:${candidates[0].id}:${Date.now()}:${randomUUID()}`).digest("hex").slice(0, 16);
-                    writeReceipt(runId, { id: receipt, pack: candidates[0].pack, at: Date.now(), expires: Date.now() + ttl });
+                    const wrote = await writeReceipt(runId, { id: receipt, pack: candidates[0].pack, at: Date.now(), expires: Date.now() + ttl });
+                    if (!wrote)
+                        await telemetry(telemetryPath, { kind: "receipt-write-failed", path: receiptPath, receipt });
                 }
                 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 } };
@@ -175,7 +180,7 @@ export default definePluginEntry({
                 return undefined;
             const runId = event?.runId ?? ctx?.runId ?? "unknown-run";
             prune();
-            const r = findReceipt(runId);
+            const r = await findReceipt(runId);
             if (r) {
                 await telemetry(telemetryPath, { kind: "gate", decision: "receipt-ok", tool: event?.toolName, runId, receipt: r.id });
                 return undefined;

package/openclaw.plugin.json

@@ -2,18 +2,55 @@
   "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"] },
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "tools": [
+      "zero_agency_route",
+      "zero_agency_status"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "required": ["registryPath"],
+    "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, "default": 900000 },
-      "gateMode": { "type": "string", "enum": ["off", "advisory", "enforce"], "default": "advisory" },
-      "consequentialTools": { "type": "array", "items": { "type": "string" }, "default": ["exec", "apply_patch"] }
+      "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": "off",
+        "description": "Receipt gate mode. EXPERIMENTAL: cross-context receipt correlation does not work in the current plugin host, so keep this off."
+      },
+      "consequentialTools": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": [
+          "exec",
+          "apply_patch"
+        ]
+      }
     }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openclaw-zero-agency",
-  "version": "0.2.4",
-  "description": "Zero Agency: capability packs, programmatic routing and a receipt gate for OpenClaw. Packs inform judgement; they never confer authority.",
+  "version": "1.0.0",
+  "description": "Capability routing for OpenClaw agents: distilled packs, a compiled registry, and routing telemetry. Packs inform judgement; they never confer authority.",
   "type": "module",
   "main": "./dist/index.js",
   "license": "MIT",