@peac/adapter-openclaw 0.12.5 → 0.12.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +42 -145
  2. package/package.json +20 -9
package/README.md CHANGED
@@ -1,8 +1,20 @@
1
1
  # @peac/adapter-openclaw
2
2
 
3
- Offline-verifiable activity records for OpenClaw sessions.
3
+ OpenClaw adapter for capturing agent tool calls as signed, offline-verifiable PEAC interaction records.
4
4
 
5
- ## Quick Start
5
+ ## Installation
6
+
7
+ ```bash
8
+ pnpm add @peac/adapter-openclaw
9
+ ```
10
+
11
+ ## What It Does
12
+
13
+ `@peac/adapter-openclaw` captures every tool call an OpenClaw agent makes and produces tamper-evident signed receipts. It uses a two-stage pipeline: a sync capture stage (under 10ms) appends hashed evidence to an append-only spool, and an async background emitter drains the spool, signs each entry, and writes individual receipt files. All inputs and outputs are SHA-256 hashed by default; plaintext is only captured for explicitly allowlisted tools.
14
+
15
+ ## How Do I Use It?
16
+
17
+ ### Quick start with activate()
6
18
 
7
19
  ```typescript
8
20
  import { activate, generateSigningKey } from '@peac/adapter-openclaw';
@@ -24,169 +36,54 @@ plugin.instance.start();
24
36
  // Records are now captured automatically via hooks.
25
37
  ```
26
38
 
27
- > Never log or print the contents of `key_ref`. Use `env:` key references in CI, `file:` for local development. Signing key files are written with 0600 permissions (owner read/write only).
28
-
29
- ## What It Records
30
-
31
- Every tool call your agent makes is captured as a tamper-evident record:
32
-
33
- - **Tool name, timing, status**: what ran, when, whether it succeeded
34
- - **Input/output digests**: SHA-256 hashes by default (payloads are never stored in plaintext unless you explicitly allowlist a tool)
35
- - **Chain linkage**: each record links to the previous one, so gaps or reordering are detectable
36
-
37
- Records are signed with your key and written to disk as individual `.peac.json` files.
38
-
39
- ## Commands
40
-
41
- ### Key Generation
42
-
43
- ```bash
44
- npx peac-keygen --output-dir .peac
45
- ```
46
-
47
- Generates a signing keypair. The private key is written with 0600 permissions. Print the `kid` and public key for registration with your infrastructure.
48
-
49
- ### Plugin Tools
50
-
51
- The plugin exposes 4 tools to the agent:
52
-
53
- | Tool | Description |
54
- | ----------------------------- | ----------------------------------------------------------------- |
55
- | `peac_receipts.status` | Spool size, last receipt time, configuration summary |
56
- | `peac_receipts.export_bundle` | Export receipts as an evidence bundle (manifest.json + receipts/) |
57
- | `peac_receipts.verify` | Verify a receipt or bundle offline |
58
- | `peac_receipts.query` | Query receipts by workflow ID, tool name, or time range |
59
-
60
- ## Configuration
61
-
62
- ### `activate()` Options
63
-
64
- ```typescript
65
- const plugin = await activate({
66
- config: {
67
- signing: {
68
- key_ref: 'env:PEAC_SIGNING_KEY', // or 'file:/path/to/key.jwk'
69
- issuer: 'https://my-org.example.com',
70
- audience: 'https://api.example.com', // optional
71
- },
72
- output_dir: '.peac/receipts', // optional (default: {dataDir}/receipts/)
73
- background: {
74
- drain_interval_ms: 1000, // optional (default: 1000)
75
- batch_size: 100, // optional (default: 100)
76
- },
77
- },
78
- dataDir: '.peac', // optional (default: ~/.openclaw/peac/)
79
- spoolOptions: {
80
- maxEntries: 100_000, // optional (default: 100,000)
81
- maxFileBytes: 104_857_600, // optional (default: 100MB)
82
- autoCommitIntervalMs: 5000, // optional (default: 5000, 0 to disable)
83
- },
84
- });
85
- ```
86
-
87
- ### Key Reference Schemes
88
-
89
- | Scheme | Format | Use Case |
90
- | ------- | ----------------------- | ---------------------------------------------- |
91
- | `env:` | `env:PEAC_SIGNING_KEY` | CI/CD, containers (key in env var as JWK JSON) |
92
- | `file:` | `file:/path/to/key.jwk` | Local development (key file on disk) |
93
-
94
- ## Compatibility
95
-
96
- | Requirement | Value |
97
- | ------------- | ---------------------------------------------------------- |
98
- | Node.js | >= 22.0.0 |
99
- | Module format | ESM (`.mjs`) and CJS (`.cjs`) dual-published |
100
- | Runtime | Node.js only (uses `fs`, `path`, `crypto`) |
101
- | Workers/Edge | Not supported (requires file system access) |
102
- | OpenClaw | v2026.2.7+ (before_tool_call or tool_result_persist hooks) |
103
-
104
- ## Architecture
105
-
106
- ### Two-Stage Pipeline
107
-
108
- ```text
109
- Tool Call Spool Receipts
110
- (sync hook) --> (append-only) --> (signed receipt)
111
- < 10ms spool.jsonl *.peac.json
112
- ```
113
-
114
- 1. **Capture stage** (sync, < 10ms target): Map OpenClaw event to a captured action, hash payloads inline, write to tamper-evident spool
115
- 2. **Emit stage** (async background): Drain spool periodically, convert to interaction evidence, sign with configured key, write receipt to output directory
116
-
117
- ### OpenClaw-to-Receipt Mapping
118
-
119
- | OpenClaw Concept | Receipt Field |
120
- | --------------------- | --------------------------- |
121
- | Session key | `workflow_id` (correlation) |
122
- | Run ID + tool_call_id | `interaction_id` (dedupe) |
123
- | Tool call params | `input.digest` |
124
- | Tool call result | `output.digest` |
125
- | Tool name | `tool.name` |
126
- | Sandbox mode | `policy.sandbox_enabled` |
127
- | Elevated flag | `policy.elevated` |
128
-
129
- ## API Reference
130
-
131
- ### High-Level (Recommended)
39
+ ### Map individual tool call events
132
40
 
133
41
  ```typescript
134
- import { activate, generateSigningKey } from '@peac/adapter-openclaw';
135
-
136
- // activate() wires all components from config
137
- const plugin = await activate(options);
138
- plugin.instance.start();
139
-
140
- // Capture events via the hook handler
141
- await plugin.hookHandler.afterToolCall(event);
42
+ import { mapToolCallEvent } from '@peac/adapter-openclaw';
142
43
 
143
- // Flush pending records into signed receipts
144
- await plugin.flush();
145
-
146
- // Clean shutdown (flushes + closes stores)
147
- await plugin.shutdown();
44
+ const result = mapToolCallEvent(event);
45
+ if (result.ok) {
46
+ console.log('Captured action:', result.action);
47
+ console.log('Warnings:', result.warnings);
48
+ }
148
49
  ```
149
50
 
150
- ### Lower-Level (Advanced)
151
-
152
- For custom wiring or when you need direct access to individual components:
51
+ ### Use lower-level components directly
153
52
 
154
53
  ```typescript
155
54
  import {
156
55
  createHookHandler,
157
56
  createReceiptEmitter,
158
57
  createBackgroundService,
159
- mapToolCallEvent,
160
58
  createSessionHistoryTailer,
161
59
  } from '@peac/adapter-openclaw';
162
60
  ```
163
61
 
164
- See the source for `createHookHandler()`, `createReceiptEmitter()`, `createBackgroundService()`, and `createSessionHistoryTailer()`.
165
-
166
- ## Security
167
-
168
- - **Privacy by default**: All inputs and outputs are hashed (SHA-256). Plaintext is only captured for explicitly allowlisted tools.
169
- - **Key protection**: Signing key files are written with 0600 permissions. Use `env:` references in CI to avoid keys on disk.
170
- - **Tamper evidence**: Each spool entry links to the previous via digest. Gaps or reordering are detectable.
171
- - **No secret logging**: The adapter never logs private key material. Only the key ID (`kid`) and public key component appear in logs.
62
+ ## Integrates With
172
63
 
173
- ## Error Codes
64
+ - `@peac/adapter-core` (Layer 4): Shared Result types
65
+ - `@peac/capture-core`: Capture session, spool store, and deduplication
66
+ - `@peac/capture-node`: File-system spool store and deduplication index
67
+ - `@peac/crypto` (Layer 2): Ed25519 signing and SHA-256 hashing
68
+ - `@peac/kernel` (Layer 0): Wire constants and types
69
+ - `@peac/schema` (Layer 1): Receipt claim schemas
174
70
 
175
- | Code | Description |
176
- | --------------------------------- | ------------------------------- |
177
- | `E_OPENCLAW_MISSING_FIELD` | Required field missing in event |
178
- | `E_OPENCLAW_INVALID_FIELD` | Invalid field value in event |
179
- | `E_OPENCLAW_SERIALIZATION_FAILED` | Payload serialization failed |
180
- | `E_OPENCLAW_SIGNING_FAILED` | Receipt signing failed |
71
+ ## For Agent Developers
181
72
 
182
- ## Warning Codes
73
+ If you are building an AI agent on OpenClaw that needs verifiable activity records:
183
74
 
184
- | Code | Description |
185
- | ----------------------------------- | --------------------------- |
186
- | `W_OPENCLAW_PAYLOAD_TRUNCATED` | Payload exceeded size limit |
187
- | `W_OPENCLAW_OPTIONAL_FIELD_MISSING` | Optional field missing |
188
- | `W_OPENCLAW_UNKNOWN_PROVIDER` | Unknown tool provider |
75
+ - Use `activate()` for the simplest setup; it wires all components from a single config object
76
+ - Use `generateSigningKey()` or the `peac-keygen` CLI to create a signing keypair
77
+ - Use `env:` key references in CI/CD and `file:` references for local development
78
+ - The plugin exposes tools (`peac_receipts.status`, `peac_receipts.verify`, `peac_receipts.query`, `peac_receipts.export_bundle`) for the agent to inspect its own receipt state
79
+ - See the [llms.txt](https://github.com/peacprotocol/peac/blob/main/llms.txt) for a concise protocol overview
189
80
 
190
81
  ## License
191
82
 
192
83
  Apache-2.0
84
+
85
+ ---
86
+
87
+ PEAC Protocol is an open source project stewarded by Originary and community contributors.
88
+
89
+ [Docs](https://www.peacprotocol.org) | [GitHub](https://github.com/peacprotocol/peac) | [Originary](https://www.originary.xyz)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@peac/adapter-openclaw",
3
- "version": "0.12.5",
3
+ "version": "0.12.7",
4
4
  "description": "OpenClaw adapter for PEAC interaction evidence capture",
5
5
  "main": "dist/index.cjs",
6
6
  "types": "dist/index.d.ts",
@@ -16,10 +16,10 @@
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",
19
- "url": "https://github.com/peacprotocol/peac.git",
19
+ "url": "git+https://github.com/peacprotocol/peac.git",
20
20
  "directory": "packages/adapters/openclaw"
21
21
  },
22
- "author": "jithinraj <7850727+jithinraj@users.noreply.github.com>",
22
+ "author": "PEAC Protocol Contributors",
23
23
  "license": "Apache-2.0",
24
24
  "bugs": {
25
25
  "url": "https://github.com/peacprotocol/peac/issues"
@@ -39,12 +39,12 @@
39
39
  "provenance": true
40
40
  },
41
41
  "dependencies": {
42
- "@peac/crypto": "0.12.5",
43
- "@peac/capture-core": "0.12.5",
44
- "@peac/adapter-core": "0.12.5",
45
- "@peac/kernel": "0.12.5",
46
- "@peac/schema": "0.12.5",
47
- "@peac/capture-node": "0.12.5"
42
+ "@peac/adapter-core": "0.12.7",
43
+ "@peac/capture-node": "0.12.7",
44
+ "@peac/kernel": "0.12.7",
45
+ "@peac/capture-core": "0.12.7",
46
+ "@peac/crypto": "0.12.7",
47
+ "@peac/schema": "0.12.7"
48
48
  },
49
49
  "devDependencies": {
50
50
  "@types/node": "^22.0.0",
@@ -52,6 +52,17 @@
52
52
  "vitest": "^4.0.0",
53
53
  "tsup": "^8.0.0"
54
54
  },
55
+ "keywords": [
56
+ "peac",
57
+ "peacprotocol",
58
+ "interaction-records",
59
+ "signed-records",
60
+ "receipts",
61
+ "originary",
62
+ "openclaw",
63
+ "capture",
64
+ "proof-capture"
65
+ ],
55
66
  "scripts": {
56
67
  "prebuild": "rm -rf dist",
57
68
  "build": "pnpm run build:js && pnpm run build:types",