openclaw-zero-agency 0.0.0-stage → 0.2.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/gate.js

@@ -0,0 +1,51 @@
+// Zero Agency receipt gate. Consequential tool calls require a routing receipt.
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { get, prune } from "./receipts.js";
+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 { /* never break a turn */ }
+}
+export default definePluginEntry({
+    id: "zero-agency-gate",
+    name: "Zero Agency Gate",
+    description: "Requires a Zero Agency routing receipt before consequential tool calls.",
+    register(api) {
+        const cfg = api.config ?? api.pluginConfig ?? {};
+        const mode = cfg.gateMode ?? "advisory";
+        const tools = cfg.consequentialTools ?? ["exec", "apply_patch"];
+        const tel = cfg.telemetryPath;
+        api.on("before_tool_call", async (event, ctx) => {
+            if (mode === "off")
+                return undefined;
+            const runId = event?.runId ?? ctx?.runId ?? "unknown-run";
+            prune();
+            const r = get(runId);
+            if (r) {
+                await telemetry(tel, { kind: "gate", decision: "receipt-ok", tool: event?.toolName, runId, receipt: r.id });
+                return undefined;
+            }
+            await telemetry(tel, { kind: "gate", decision: mode === "enforce" ? "blocked" : "advisory-miss", tool: event?.toolName, runId });
+            if (mode !== "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(tel, { kind: "gate", decision, tool: event?.toolName, runId, receipt: null });
+                    },
+                },
+            };
+        }, { matcher: tools, priority: 50 });
+    },
+});

package/dist/receipts.js

@@ -0,0 +1,22 @@
+const KEY = Symbol.for("openclaw.zero-agency.receipts.v1");
+function store() {
+    const g = globalThis;
+    if (!g[KEY])
+        g[KEY] = new Map();
+    return g[KEY];
+}
+export function put(runId, receipt) {
+    store().set(runId, receipt);
+}
+export function get(runId) {
+    return store().get(runId);
+}
+export function prune() {
+    const t = Date.now();
+    for (const [k, v] of store())
+        if (v.expires < t)
+            store().delete(k);
+}
+export function size() {
+    return store().size;
+}

package/dist/tools.js

@@ -0,0 +1,143 @@
+// Zero Agency — capability routing tools. Packs inform judgement; they never confer authority.
+import { Type } from "typebox";
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { readFile, appendFile, mkdir } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { put, prune, size } from "./receipts.js";
+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 defineToolPlugin({
+    id: "zero-agency",
+    name: "Zero Agency",
+    description: "Capability routing for the fleet. Packs inform judgement; they never confer authority.",
+    configSchema: Type.Object({
+        registryPath: Type.String({ description: "Absolute path to capabilities.json (read-only)." }),
+        telemetryPath: Type.Optional(Type.String({ description: "JSONL telemetry path." })),
+        receiptTtlMs: Type.Optional(Type.Integer({ minimum: 1000 })),
+        gateMode: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("advisory"), Type.Literal("enforce")], { description: "Receipt gate mode (default advisory)." })),
+        consequentialTools: Type.Optional(Type.Array(Type.String(), { description: "Tool ids gated by receipt." })),
+    }),
+    tools: (tool) => [
+        tool({
+            name: "zero_agency_route",
+            label: "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(params, config, context) {
+                context?.signal?.throwIfAborted?.();
+                const q = norm(params.task);
+                const limit = params.limit ?? 3;
+                const ttl = config.receiptTtlMs ?? 900000;
+                let candidates = [];
+                let note = "";
+                try {
+                    const reg = await loadRegistry(config.registryPath);
+                    candidates = (reg.capabilities ?? [])
+                        .map((c) => ({ c, ...score(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 }));
+                    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 = context?.runId ?? context?.sessionId ?? "unknown-run";
+                    receipt = createHash("sha256").update(`${runId}:${candidates[0].id}:${Date.now()}:${randomUUID()}`).digest("hex").slice(0, 16);
+                    put(runId, { id: receipt, pack: candidates[0].pack, at: Date.now(), expires: Date.now() + ttl });
+                    prune();
+                }
+                await telemetry(config.telemetryPath, {
+                    kind: "route", agent: context?.agentId ?? null,
+                    session: context?.sessionId ?? null, query: params.task.slice(0, 200),
+                    selected: candidates[0]?.id ?? null, candidates: candidates.length, receipt,
+                });
+                return { candidates, receipt, note };
+            },
+        }),
+        tool({
+            name: "zero_agency_status",
+            label: "Zero Agency Status",
+            description: "Report the 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(_params, config) {
+                try {
+                    const reg = await loadRegistry(config.registryPath);
+                    const caps = reg.capabilities ?? [];
+                    return {
+                        registry: config.registryPath,
+                        capabilities: caps.length,
+                        tokens: caps.reduce((s, c) => s + (c.tokens ?? 0), 0),
+                        receipts: size(),
+                        registryError: null,
+                    };
+                }
+                catch (e) {
+                    return { registry: config.registryPath, capabilities: 0, tokens: 0, receipts: size(), registryError: e?.message ?? "unknown" };
+                }
+            },
+        }),
+    ],
+});

package/openclaw.plugin.json

@@ -0,0 +1,59 @@
+{
+  "id": "zero-agency",
+  "name": "Zero Agency",
+  "description": "Capability routing for the fleet. Packs inform judgement; they never confer authority.",
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "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."
+      }
+    }
+  },
+  "version": "0.2.0",
+  "contracts": {
+    "tools": [
+      "zero_agency_route",
+      "zero_agency_status"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "openclaw-zero-agency",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.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/tools.js",
+      "./dist/gate.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.10.1",
+      "minGatewayVersion": "2026.10.1"
+    }
+  }
+}