openclaw-zero-agency 1.0.1 → 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,20 +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 && (x.c.status ?? 'draft') === 'live')
+                        .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 }));
-                    const drafts = (reg.capabilities ?? [])
-                        .filter((c) => (c.status ?? 'draft') !== 'live')
-                        .filter((c) => score(c, q).score > 0);
                     note = candidates.length
                         ? `load ${candidates[0].pack} before acting`
-                        : drafts.length
-                            ? `no live capability matched; ${drafts.length} draft pack(s) matched but are unpublished: ${drafts.map((c) => c.id).join(", ")}`
-                            : "no capability matched; if this action is consequential, stop and ask";
+                        : 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"}`;
@@ -162,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.1",
+  "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/dist/tools.js

@@ -1,148 +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 && (x.c.status ?? 'draft') === 'live')
-                        .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 }));
-                    const drafts = (reg.capabilities ?? [])
-                        .filter((c) => (c.status ?? 'draft') !== 'live')
-                        .filter((c) => score(c, q).score > 0);
-                    note = candidates.length
-                        ? `load ${candidates[0].pack} before acting`
-                        : drafts.length
-                            ? `no live capability matched; ${drafts.length} draft pack(s) matched but are unpublished: ${drafts.map((c) => c.id).join(", ")}`
-                            : "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" };
-                }
-            },
-        }),
-    ],
-});