@atbash/atbash-openclaw 0.1.17-dev.4 → 0.1.17-dev.5

package/README.md

@@ -7,11 +7,10 @@ If you're not using OpenClaw and want to use ATBASH from your own code, install
 ## Install
 
 ```bash
-openclaw plugins install @atbash/atbash-openclaw        # production
-openclaw plugins install @atbash/atbash-openclaw@dev    # development
+openclaw plugins install @atbash/atbash-openclaw@0.1.17-dev.4
 ```
 
-**The judge endpoint and chain ids are compiled into the build**, so the npm tag selects the environment. Install the plain tag if your agent was onboarded on production, the `@dev` tag if it was onboarded on development; `openclaw plugins list` shows which you have (a `-dev.N` version is the development build). No configuration repoints a build afterwards — the wrong one loads cleanly, fires its hook, and then fails every judge call because the agent does not exist on the chain that build targets. Organization names are not unique across environments, so a resolving org name is not proof the build is right.
+**The judge endpoint and chain ids are compiled into the build**, so the version selects the environment. A `-dev.N` version targets the development environment. `openclaw plugins list` shows which you have. No configuration repoints a build afterwards — the wrong one loads cleanly, fires its hook, and then fails every judge call because the agent does not exist on the chain that build targets. Organization names are not unique across environments, so a resolving org name is not proof the build is right.
 
 The plugin signs audit transactions locally with your agent's secp256k1 private key. The key never leaves your machine; only signed bytes plus the corresponding public key are transmitted.
 
@@ -67,6 +66,51 @@ already there:
 }
 ```
 
+### Advanced configuration
+
+The snippet below shows every supported config field with inline comments. Remove fields you don't need — all are optional except `orgName` (required when your org is on a private chain).
+
+```jsonc
+{
+  "plugins": {
+    "entries": {
+      "atbash-openclaw": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "enforceDecision": true,
+          "chromiaSecretPath": "~/.config/atbash/guard-client-key",
+          "orgName": "<your-org-name>",
+          "debug": false,
+
+          // --- Memory guard (optional) ---
+          // Root directory used to locate the memory pointer file and MEMORY.md.
+          "memoryWorkspaceDir": "~/.openclaw/workspace",
+          // Or set an explicit path to MEMORY.md (overrides memoryWorkspaceDir):
+          // "memoryFilePath": "~/.openclaw/workspace/MEMORY.md",
+          // How long (ms) to trust the local memory-chain cache before re-fetching.
+          "memorySyncTTLMs": 30000,
+          // Block memory reads when a rolled-back version scores below this (1–10).
+          // Default 1 = warn only. Raise to e.g. 3 to refuse poisoned rollbacks.
+          "memoryRollbackMinScore": 1,
+          // Additional path substrings to classify as memory (extends SDK built-ins).
+          // "memoryPathPatterns": ["/my-agent/memory/"],
+
+          // --- Self-hosted judge (optional, advanced) ---
+          // "judgeEndpoint": "https://your-judge.example.com/api/v1/judge",
+          // "judgeEndpointPolicy": "self-hosted",
+          // "judgeVerifyPubKey": "<66-hex-char-secp256k1-pubkey>"
+        },
+        "hooks": {
+          "allowConversationAccess": true,
+          "allowPromptInjection": true
+        }
+      }
+    }
+  }
+}
+```
+
 The plugin id is `atbash-openclaw` — it comes from the `id` field in this package's `openclaw.plugin.json`,
 not from the npm package name. A `plugins.entries` key that does not match the id is not an error: the
 plugin loads unconfigured and audits nothing.
@@ -76,10 +120,18 @@ plugin loads unconfigured and audits nothing.
 | Field | Type | Default | What it does |
 |---|---|---|---|
 | `enabled` | bool | `true` | Master switch. `false` = plugin returns immediately. |
-| `enforceDecision` | bool | `true` | Surfaced to logs. The plugin always blocks on `BLOCK`. |
+| `enforceDecision` | bool | `true` | Fail-closed switch. When `true` (default), verdicts of `BLOCK`, `HOLD`, `ERROR`, and any unrecognized verdict block the tool call. When `false`, the plugin runs fail-open: all verdicts allow the tool call through and the outcome is only logged — useful for monitoring without enforcement. |
 | `chromiaSecretPath` | string | `~/.config/atbash/guard-client-key` | Path to the agent key file. Supports `~/`. |
 | `orgName` | string | — | Organization the agent was onboarded under, spelled as the dashboard shows it. The plugin resolves which chain to query from this, so it is required when the org is on a private chain. |
 | `debug` | bool | `false` | When `true`, logs a one-line probe for every `before_tool_call` showing `toolName`, top-level event/ctx/args keys, and whether the call was classified as a memory write. Useful for verifying memory-write classifier coverage against real traffic. Logs shape only — argument values are never printed. |
+| `judgeEndpoint` | string | — | Override the judge URL. Leave unset to use the compiled-in default for the installed environment (prod or dev). |
+| `judgeEndpointPolicy` | `"default"` \| `"self-hosted"` | `"default"` | Set to `"self-hosted"` when pointing at your own judge; requires `judgeVerifyPubKey`. |
+| `judgeVerifyPubKey` | string | — | 66-char secp256k1 compressed pubkey used to verify the self-hosted judge response signature. Required when `judgeEndpointPolicy` is `"self-hosted"`. |
+| `memoryPathPatterns` | string[] | SDK defaults | Extra path substrings the memory classifier uses to identify memory-shaped files (e.g. `"/my-agent/memory/"`). Extends, does not replace, the SDK's built-in list. |
+| `memoryWorkspaceDir` | string | `process.cwd()` | Workspace root used to locate the memory pointer file and `MEMORY.md`. Supports `~/`. |
+| `memoryFilePath` | string | `<memoryWorkspaceDir>/MEMORY.md` | Explicit path to the agent's MEMORY.md. Overrides the `memoryWorkspaceDir`-relative default. Supports `~/`. |
+| `memorySyncTTLMs` | integer | `30000` | How long (ms) to trust the locally cached memory chain pointer before re-fetching from the chain. Lower values increase freshness at the cost of more chain queries. |
+| `memoryRollbackMinScore` | integer (1–10) | `1` | Block memory reads when a rolled-back version's safety score is below this threshold. Default `1` means warn only, never block. Raise to e.g. `3` to refuse reading poisoned rollbacks. |
 
 ## Updating
 
@@ -123,6 +175,9 @@ Check `enabled: true` is set both on the entry (`plugins.entries["atbash-opencla
 **Every tool call is blocked, even safe ones.**
 The plugin is fail-closed: any pipeline error blocks. Look for `[atbash] …` warnings in the OpenClaw log. Most often: missing key, expired key, or restricted egress.
 
+**Plugin loads but config is not applied (audit runs on defaults).**
+The `plugins.entries` key must be exactly `"atbash-openclaw"` — the plugin's id from its `openclaw.plugin.json`. Former names (`"openclaw"`, `"atbash-plugin"`) are silently ignored; the plugin logs a warning at startup but otherwise runs unconfigured. Check the OpenClaw startup log for `[atbash] found config under former plugin id` and move the settings block to `plugins.entries["atbash-openclaw"]`.
+
 ## Maintainer release contract
 
 Development packages are released only through the protected **Publish development package** GitHub workflow. The workflow requires the `npm` environment, the exact `PUBLISH` confirmation, and npm trusted-publisher configuration for this repository and workflow. It never accepts a registry token from package source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atbash/atbash-openclaw",
-  "version": "0.1.17-dev.4",
+  "version": "0.1.17-dev.5",
   "description": "OpenClaw ATBASH tool-audit plugin. Thin adapter that maps OpenClaw's before_tool_call hook onto @atbash/sdk.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",