@peac/adapter-openclaw 0.10.10 → 0.10.12

package/README.md

@@ -1,82 +1,122 @@
 # @peac/adapter-openclaw
 
-OpenClaw adapter for PEAC interaction evidence capture.
+Offline-verifiable activity records for OpenClaw sessions.
 
-## Overview
+## Quick Start
+
+```typescript
+import { activate, generateSigningKey } from '@peac/adapter-openclaw';
+
+// Generate a signing key (one-time setup)
+const key = await generateSigningKey({ outputDir: '.peac' });
+
+// Activate the plugin
+const plugin = await activate({
+  config: {
+    signing: {
+      key_ref: `file:${key.keyPath}`,
+      issuer: 'https://my-org.example.com',
+    },
+  },
+});
+
+plugin.instance.start();
+// Records are now captured automatically via hooks.
+```
+
+> 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).
+
+## What It Records
 
-`@peac/adapter-openclaw` provides a complete capture pipeline for recording OpenClaw tool calls as PEAC interaction evidence. It includes:
+Every tool call your agent makes is captured as a tamper-evident record:
 
-- **Mapper**: OpenClaw tool call events -> PEAC `CapturedAction`
-- **Hooks**: Sync capture bindings (< 10ms target)
-- **Emitter**: Background receipt signing and persistence
-- **Tailer**: Session history fallback for resilience
+- **Tool name, timing, status** -- what ran, when, whether it succeeded
+- **Input/output digests** -- SHA-256 hashes by default (payloads are never stored in plaintext unless you explicitly allowlist a tool)
+- **Chain linkage** -- each record links to the previous one, so gaps or reordering are detectable
 
-## Installation
+Records are signed with your key and written to disk as individual `.peac.json` files.
+
+## Commands
+
+### Key Generation
 
 ```bash
-pnpm add @peac/adapter-openclaw
+npx peac-keygen --output-dir .peac
 ```
 
-## Quick Start
+Generates a signing keypair. The private key is written with 0600 permissions. Print the `kid` and public key for registration with your infrastructure.
 
-```typescript
-import { createCaptureSession, createHasher } from '@peac/capture-core';
-import { createInMemorySpoolStore, createInMemoryDedupeIndex } from '@peac/capture-core/testkit';
-import { createHookHandler, mapToolCallEvent } from '@peac/adapter-openclaw';
-
-// Create a capture session
-const session = createCaptureSession({
-  store: createInMemorySpoolStore(),
-  dedupe: createInMemoryDedupeIndex(),
-  hasher: createHasher(),
-});
+### Plugin Tools
+
+The plugin exposes 4 tools to the agent:
 
-// Create a hook handler
-const handler = createHookHandler({
-  session,
+| Tool                          | Description                                                       |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `peac_receipts.status`        | Spool size, last receipt time, configuration summary              |
+| `peac_receipts.export_bundle` | Export receipts as an evidence bundle (manifest.json + receipts/) |
+| `peac_receipts.verify`        | Verify a receipt or bundle offline                                |
+| `peac_receipts.query`         | Query receipts by workflow ID, tool name, or time range           |
+
+## Configuration
+
+### `activate()` Options
+
+```typescript
+const plugin = await activate({
   config: {
-    platform: 'openclaw',
-    platform_version: '0.2.0',
+    signing: {
+      key_ref: 'env:PEAC_SIGNING_KEY', // or 'file:/path/to/key.jwk'
+      issuer: 'https://my-org.example.com',
+      audience: 'https://api.example.com', // optional
+    },
+    output_dir: '.peac/receipts', // optional (default: {dataDir}/receipts/)
+    background: {
+      drain_interval_ms: 1000, // optional (default: 1000)
+      batch_size: 100, // optional (default: 100)
+    },
+  },
+  dataDir: '.peac', // optional (default: ~/.openclaw/peac/)
+  spoolOptions: {
+    maxEntries: 100_000, // optional (default: 100,000)
+    maxFileBytes: 104_857_600, // optional (default: 100MB)
+    autoCommitIntervalMs: 5000, // optional (default: 5000, 0 to disable)
   },
 });
+```
 
-// Handle OpenClaw tool call events
-const result = await handler.afterToolCall({
-  tool_call_id: 'call_123',
-  run_id: 'run_abc',
-  tool_name: 'web_search',
-  started_at: '2024-02-01T10:00:00Z',
-  completed_at: '2024-02-01T10:00:01Z',
-  status: 'ok',
-  input: { query: 'hello world' },
-  output: { results: ['result1'] },
-});
+### Key Reference Schemes
 
-if (result.success) {
-  console.log('Captured:', result.entry.entry_digest);
-}
+| Scheme  | Format                  | Use Case                                       |
+| ------- | ----------------------- | ---------------------------------------------- |
+| `env:`  | `env:PEAC_SIGNING_KEY`  | CI/CD, containers (key in env var as JWK JSON) |
+| `file:` | `file:/path/to/key.jwk` | Local development (key file on disk)           |
 
-await handler.close();
-```
+## Compatibility
+
+| Requirement   | Value                                                      |
+| ------------- | ---------------------------------------------------------- |
+| Node.js       | >= 22.0.0                                                  |
+| Module format | ESM (`.mjs`) and CJS (`.cjs`) dual-published               |
+| Runtime       | Node.js only (uses `fs`, `path`, `crypto`)                 |
+| Workers/Edge  | Not supported (requires file system access)                |
+| OpenClaw      | v2026.2.7+ (before_tool_call or tool_result_persist hooks) |
 
 ## Architecture
 
 ### Two-Stage Pipeline
 
-1. **Capture Stage** (sync, < 10ms target)
-   - Map OpenClaw event to `CapturedAction`
-   - Hash payloads inline (truncate large payloads)
-   - Write to tamper-evident spool
+```text
+Tool Call        Spool             Receipts
+(sync hook) --> (append-only)  --> (signed receipt)
+< 10ms          spool.jsonl        *.peac.json
+```
 
-2. **Emit Stage** (async background)
-   - Drain spool periodically
-   - Convert to `InteractionEvidenceV01`
-   - Sign with configured key
-   - Write receipt to output
+1. **Capture stage** (sync, < 10ms target): Map OpenClaw event to a captured action, hash payloads inline, write to tamper-evident spool
+2. **Emit stage** (async background): Drain spool periodically, convert to interaction evidence, sign with configured key, write receipt to output directory
 
-### OpenClaw to PEAC Mapping
+### OpenClaw-to-Receipt Mapping
 
-| OpenClaw Concept      | PEAC Location               |
+| OpenClaw Concept      | Receipt Field               |
 | --------------------- | --------------------------- |
 | Session key           | `workflow_id` (correlation) |
 | Run ID + tool_call_id | `interaction_id` (dedupe)   |
@@ -88,85 +128,47 @@ await handler.close();
 
 ## API Reference
 
-### Mapper
-
-```typescript
-import { mapToolCallEvent, mapToolCallEventBatch } from '@peac/adapter-openclaw';
-
-// Map single event
-const result = mapToolCallEvent(event, config);
-if (result.success) {
-  console.log(result.action);
-}
-
-// Map batch
-const results = mapToolCallEventBatch(events, config);
-```
-
-### Hook Handler
+### High-Level (Recommended)
 
 ```typescript
-import { createHookHandler, captureBatch, captureParallel } from '@peac/adapter-openclaw';
+import { activate, generateSigningKey } from '@peac/adapter-openclaw';
 
-const handler = createHookHandler({
-  session,
-  config: { platform: 'openclaw' },
-  onCapture: (result, event) => {
-    console.log('Captured:', result);
-  },
-});
+// activate() wires all components from config
+const plugin = await activate(options);
+plugin.instance.start();
 
-// Single event
-await handler.afterToolCall(event);
+// Capture events via the hook handler
+await plugin.hookHandler.afterToolCall(event);
 
-// Batch (sequential)
-await captureBatch(handler, events);
+// Flush pending records into signed receipts
+await plugin.flush();
 
-// Batch (parallel - non-deterministic order)
-await captureParallel(handler, events);
+// Clean shutdown (flushes + closes stores)
+await plugin.shutdown();
 ```
 
-### Background Emitter
+### Lower-Level (Advanced)
 
-```typescript
-import { createReceiptEmitter, createBackgroundService } from '@peac/adapter-openclaw';
-
-const emitter = createReceiptEmitter({
-  signer,
-  writer,
-  config: { platform: 'openclaw' },
-});
+For custom wiring or when you need direct access to individual components:
 
-const service = createBackgroundService({
-  emitter,
-  getPendingEntries: () => spoolStore.getPending(),
-  markEmitted: (digest) => dedupeIndex.markEmitted(digest),
-  drainIntervalMs: 1000,
-});
-
-service.start();
-// ... later
-service.stop();
+```typescript
+import {
+  createHookHandler,
+  createReceiptEmitter,
+  createBackgroundService,
+  mapToolCallEvent,
+  createSessionHistoryTailer,
+} from '@peac/adapter-openclaw';
 ```
 
-### Session History Tailer (Fallback)
+See the source for `createHookHandler()`, `createReceiptEmitter()`, `createBackgroundService()`, and `createSessionHistoryTailer()`.
 
-```typescript
-import { createSessionHistoryTailer } from '@peac/adapter-openclaw';
+## Security
 
-const tailer = createSessionHistoryTailer({
-  handler,
-  sessionId: 'session_123',
-  fetchHistory: async (sessionId, afterEventId) => {
-    return openclaw.sessions.getHistory(sessionId, { after: afterEventId });
-  },
-  pollIntervalMs: 1000,
-});
-
-tailer.start();
-// ... later
-tailer.stop();
-```
+- **Privacy by default**: All inputs and outputs are hashed (SHA-256). Plaintext is only captured for explicitly allowlisted tools.
+- **Key protection**: Signing key files are written with 0600 permissions. Use `env:` references in CI to avoid keys on disk.
+- **Tamper evidence**: Each spool entry links to the previous via digest. Gaps or reordering are detectable.
+- **No secret logging**: The adapter never logs private key material. Only the key ID (`kid`) and public key component appear in logs.
 
 ## Error Codes
 

package/dist/activate.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @peac/adapter-openclaw - Plugin Activation
+ *
+ * High-level entry point that wires together all adapter components
+ * from config. Calls existing functions (resolveSigner, createPluginInstance,
+ * createFileReceiptWriter, etc.) -- no logic duplication.
+ *
+ * Usage:
+ *   const result = await activate({ config, logger });
+ *   result.instance.start();
+ *
+ * When OpenClaw's plugin loader gains a stable activation shape,
+ * add a thin validated wrapper at that time.
+ */
+import type { OpenClawAdapterConfig } from './types.js';
+import type { PluginLogger, PluginInstance, PluginTool } from './plugin.js';
+import type { OpenClawHookHandler } from './hooks.js';
+import type { FsSpoolStoreOptions } from '@peac/capture-node';
+/**
+ * Options for activating the plugin.
+ */
+export interface ActivateOptions {
+    /** Adapter configuration (signing, capture, correlation, background). */
+    config: ActivateConfig;
+    /** Logger instance. */
+    logger?: PluginLogger;
+    /** Data directory for spool, dedupe, and signing key. Default: ~/.openclaw/peac/ */
+    dataDir?: string;
+    /** Spool store options override. */
+    spoolOptions?: Partial<Pick<FsSpoolStoreOptions, 'maxEntries' | 'maxFileBytes' | 'autoCommitIntervalMs' | 'lockOptions'>>;
+}
+/**
+ * Configuration for activate(). Extends OpenClawAdapterConfig with
+ * required signing fields.
+ */
+export interface ActivateConfig extends OpenClawAdapterConfig {
+    /** Signing configuration (required for activation). */
+    signing: {
+        /** Key reference: env:VAR_NAME or file:/path */
+        key_ref: string;
+        /** Issuer URI for receipts */
+        issuer: string;
+        /** Optional audience URI */
+        audience?: string;
+    };
+    /** Output directory for receipt files. Default: {dataDir}/receipts/ */
+    output_dir?: string;
+    /** Background emitter settings. */
+    background?: {
+        drain_interval_ms?: number;
+        batch_size?: number;
+    };
+}
+/**
+ * Result of activating the plugin.
+ */
+export interface ActivateResult {
+    /** The running plugin instance. */
+    instance: PluginInstance;
+    /** The 4 plugin tools (status, export, verify, query). */
+    tools: PluginTool[];
+    /** Hook handler for tool call events. */
+    hookHandler: OpenClawHookHandler;
+    /** Data directory used. */
+    dataDir: string;
+    /** Flush pending spool entries into signed receipts. */
+    flush: () => Promise<void>;
+    /** Shut down the plugin cleanly. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Activate the PEAC evidence export plugin.
+ *
+ * This is the single canonical entry point. It:
+ * 1. Resolves the signing key from config (env: or file:)
+ * 2. Creates durable stores (FsSpoolStore + FsDedupeIndex)
+ * 3. Creates the receipt writer
+ * 4. Creates the plugin instance (session + hooks + emitter)
+ * 5. Creates the 4 plugin tools
+ * 6. Logs startup diagnostics
+ *
+ * @throws If signing key cannot be resolved
+ * @throws If data directory is not writable
+ * @throws If spool lockfile cannot be acquired
+ */
+export declare function activate(options: ActivateOptions): Promise<ActivateResult>;
+//# sourceMappingURL=activate.d.ts.map

package/dist/activate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activate.d.ts","sourceRoot":"","sources":["../src/activate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAc9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,MAAM,EAAE,cAAc,CAAC;IACvB,uBAAuB;IACvB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,YAAY,CAAC,EAAE,OAAO,CACpB,IAAI,CACF,mBAAmB,EACnB,YAAY,GAAG,cAAc,GAAG,sBAAsB,GAAG,aAAa,CACvE,CACF,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,cAAe,SAAQ,qBAAqB;IAC3D,uDAAuD;IACvD,OAAO,EAAE;QACP,gDAAgD;QAChD,OAAO,EAAE,MAAM,CAAC;QAChB,8BAA8B;QAC9B,MAAM,EAAE,MAAM,CAAC;QACf,4BAA4B;QAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,UAAU,CAAC,EAAE;QACX,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,QAAQ,EAAE,cAAc,CAAC;IACzB,0DAA0D;IAC1D,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,yCAAyC;IACzC,WAAW,EAAE,mBAAmB,CAAC;IACjC,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,oCAAoC;IACpC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AA4BD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8FhF"}