openclaw-zero-agency 1.0.0 → 1.2.0

package/dist/index.js

@@ -95,6 +95,21 @@ function score(cap, q) {
     s += 0.5 * dw.filter((w) => q.includes(w)).length;
     return { score: s, hits };
 }
+const DAY_MS = 86_400_000;
+function ageDays(cap) {
+    if (!cap.reviewed_at)
+        return null;
+    const t = Date.parse(cap.reviewed_at);
+    if (Number.isNaN(t))
+        return null;
+    return Math.floor((Date.now() - t) / DAY_MS);
+}
+// A pack that has not been re-reviewed within maxPackAgeDays is stale: upstream
+// guidance rots, so promotion expires instead of persisting forever.
+function isStale(cap, maxDays) {
+    const a = ageDays(cap);
+    return a !== null && a > maxDays;
+}
 async function telemetry(path, record) {
     if (!path)
         return;
@@ -106,8 +121,8 @@ async function telemetry(path, record) {
 }
 export default definePluginEntry({
     id: "zero-agency",
-    name: "Zero Agency",
-    description: "Capability routing with a receipt gate. Packs inform judgement; they never confer authority.",
+    name: "Use Agency",
+    description: "Capability routing with evidence-gated pack promotion. Packs inform judgement; they never confer authority.",
     register(api) {
         // api.config is the GLOBAL gateway config; plugin-scoped config lives on api.pluginConfig.
         const cfg = api.pluginConfig ?? {};
@@ -118,6 +133,7 @@ export default definePluginEntry({
         const gateMode = cfg.gateMode ?? "advisory";
         const consequential = cfg.consequentialTools ?? ["exec", "apply_patch"];
         const ttl = cfg.receiptTtlMs ?? 900000;
+        const maxPackAgeDays = cfg.maxPackAgeDays ?? 180;
         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. Returns the governing pack and logs the routing decision.",
@@ -136,13 +152,24 @@ export default definePluginEntry({
                 let note = "";
                 try {
                     const reg = await loadRegistry(registryPath);
-                    candidates = (reg.capabilities ?? [])
+                    const matched = (reg.capabilities ?? [])
                         .map((c) => ({ c, ...score(c, q) }))
-                        .filter((x) => x.score > 0)
+                        .filter((x) => x.score > 0);
+                    const evaluated = matched.filter((x) => (x.c.status ?? 'draft') === 'evaluated');
+                    const stale = evaluated.filter((x) => isStale(x.c, maxPackAgeDays));
+                    const drafts = matched.filter((x) => (x.c.status ?? 'draft') !== 'evaluated');
+                    candidates = evaluated
+                        .filter((x) => !isStale(x.c, maxPackAgeDays))
                         .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";
+                    note = candidates.length
+                        ? `load ${candidates[0].pack} before acting`
+                        : stale.length
+                            ? `no fresh capability matched; ${stale.length} evaluated pack(s) exceeded maxPackAgeDays (${maxPackAgeDays}) and need re-review: ${stale.map((x) => x.c.id).join(", ")}`
+                            : drafts.length
+                                ? `no evaluated capability matched; ${drafts.length} draft pack(s) matched but are unpublished: ${drafts.map((x) => x.c.id).join(", ")}`
+                                : "no capability matched; if this action is consequential, stop and ask";
                 }
                 catch (e) {
                     note = `registry unavailable: ${e?.message ?? "unknown"}`;
@@ -155,23 +182,30 @@ export default definePluginEntry({
                     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 });
+                const audience = ctx?.memoryAudience ?? null;
+                const agentId = audience?.agentId ?? ctx?.agentId ?? null;
+                const sessionKey = audience?.sessionKey ?? ctx?.sessionKey ?? null;
+                const sessionId = audience?.sessionId ?? ctx?.sessionId ?? null;
+                await telemetry(telemetryPath, { kind: "route", agent: agentId, session: sessionKey, sessionId, audience: audience?.kind ?? null, query: params.task.slice(0, 200), selected: candidates[0]?.id ?? null, pack: candidates[0]?.pack ?? 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.",
+            description: "Report Zero Agency registry state: capability counts by promotion state, token total, pack freshness 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 } };
+                    const evaluated = caps.filter((c) => (c.status ?? 'draft') === 'evaluated');
+                    const stale = evaluated.filter((c) => isStale(c, maxPackAgeDays)).map((c) => c.id);
+                    const summary = `zero-agency: ${caps.length} capabilities (${evaluated.length} evaluated, ${caps.length - evaluated.length} draft)`;
+                    return { content: [{ type: "text", text: summary }], details: { registry: registryPath, capabilities: caps.length, evaluated: evaluated.length, draft: caps.length - evaluated.length, stale, maxPackAgeDays, 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" } };
+                    return { content: [{ type: "text", text: `zero-agency: registry error` }], details: { registry: registryPath, capabilities: 0, evaluated: 0, draft: 0, stale: [], maxPackAgeDays, tokens: 0, receipts: store().size, registryError: e?.message ?? "unknown" } };
                 }
             },
         });

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "zero-agency",
-  "name": "Zero Agency",
-  "description": "Capability routing with a receipt gate. Packs inform judgement; they never confer authority.",
+  "name": "Use Agency",
+  "description": "Capability routing with evidence-gated pack promotion. Packs inform judgement; they never confer authority.",
   "activation": {
     "onStartup": true
   },
@@ -50,6 +50,12 @@
           "exec",
           "apply_patch"
         ]
+      },
+      "maxPackAgeDays": {
+        "type": "integer",
+        "minimum": 1,
+        "default": 180,
+        "description": "Screened packs older than this (by reviewed_at) are not routed and must be re-reviewed."
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-zero-agency",
-  "version": "1.0.0",
+  "version": "1.2.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",

package/LICENSE

@@ -1,21 +0,0 @@
-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,50 +0,0 @@
-# openclaw-zero-agency
-
-Capability routing for OpenClaw agents.
-
-**Packs inform judgement; they never confer authority.**
-
-## 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
-
-```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"
-        }
-      }
-    }
-  }
-}
-```
-
-`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/tools.js

@@ -1,143 +0,0 @@
-// 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/tools",
-    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" };
-                }
-            },
-        }),
-    ],
-});