usertrust-openclaw 1.3.0 → 1.4.0

package/README.md

@@ -1,264 +1,65 @@
-# usertrust™
+# usertrust-openclaw
 
-Financial governance for AI agents. Every LLM call becomes an immutable, auditable transaction.
-
-```typescript
-import { trust } from "usertrust";
-import Anthropic from "@anthropic-ai/sdk";
-
-// dryRun: true — skips TigerBeetle so you can try instantly.
-// Audit chain and policy engine still run.
-const client = await trust(new Anthropic(), { dryRun: true, budget: 50_000 });
-
-const { response, governance } = await client.messages.create({
-  model: "claude-sonnet-4.6",
-  max_tokens: 1024,
-  messages: [{ role: "user", content: "Analyze this contract" }],
-});
-
-console.log(governance);
-
-// REQUIRED — process hangs without this
-await client.destroy();
-```
-
-That's it. One function wraps any supported LLM client. Every call is metered, audited, and policy-checked.
-
-### Expected Output
-
-The `governance` receipt returned from every call:
-
-```
-{
-  cost: 42,
-  budgetRemaining: 49958,
-  transferId: "tx_m4k7p2_a1b2c3",
-  auditHash: "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-  settled: true,
-  model: "claude-sonnet-4.6",
-  provider: "anthropic",
-  inputTokens: 12,
-  outputTokens: 28
-}
-```
+[`usertrust`](https://usertrust.ai) governance plugin for **OpenClaw**. Adds budget enforcement, policy gates, PII/injection scanning, and a hash-chained audit trail to every LLM call — with zero changes to your agent code. Install the plugin and every streamed call is governed.
 
 ## Install
 
 ```bash
-npx usertrust init
-```
-
-This creates a `.usertrust/` vault in your project root with default config, policies, and an empty audit chain.
-
-## Integration
-
-Works with Anthropic, OpenAI, and Google AI SDKs:
-
-```typescript
-import { trust } from "usertrust";
-import Anthropic from "@anthropic-ai/sdk";
-import OpenAI from "openai";
-
-// Anthropic
-const anthropic = await trust(new Anthropic());
-const { response, governance } = await anthropic.messages.create({ ... });
-
-// OpenAI
-const openai = await trust(new OpenAI());
-const { response, governance } = await openai.chat.completions.create({ ... });
-
-// With options (full mode — requires TigerBeetle)
-const client = await trust(new Anthropic(), {
-  budget: 100_000,
-});
-```
-
-Every call returns `{ response, governance }` where `governance` is a receipt:
-
-```typescript
-{
-  transferId: "tx_m4k7r2_a1b2c3",
-  cost: 142,
-  budgetRemaining: 49_858,
-  auditHash: "a3f8...",
-  settled: true,
-  model: "claude-sonnet-4.6",
-  provider: "anthropic",
-  timestamp: "2026-03-16T12:00:00.000Z"
-}
-```
-
-## Inspect
-
-```bash
-npx usertrust inspect
-```
-
-```
-=== Vault Report ===
-Chain:    847 events · 12 segments
-Budget:   38,420 / 50,000 UT remaining
-Models:   claude-sonnet-4-6 (412) · gpt-4o (289) · gemini-2.0-flash (146)
-Policy:   3 rules active · 0 violations
-PII:      2 warnings · 0 blocks
-Merkle:   a3f8c1...d92b (root)
-```
-
-## CLI
-
-All commands support `--json` for machine-readable output.
-
-```bash
-usertrust init          # Create .usertrust/ vault
-usertrust inspect       # Vault bank statement
-usertrust health        # Entropy diagnostics (6 signals, 0-100 score)
-usertrust verify        # Verify audit chain integrity
-usertrust snapshot      # Checkpoint/restore vault state
-usertrust tb            # TigerBeetle process management
-usertrust completions   # Shell completions (bash, zsh, fish)
-```
-
-### JSON output
-
-Every command supports `--json` for scripting and CI:
-
-```bash
-usertrust inspect --json | jq '.data.remaining'
-```
-
-### Shell completions
-
-```bash
-# Bash
-usertrust completions bash > ~/.local/share/bash-completion/completions/usertrust
-
-# Zsh
-usertrust completions zsh > "${fpath[1]}/_usertrust"
-
-# Fish
-usertrust completions fish > ~/.config/fish/completions/usertrust.fish
+openclaw plugins install usertrust-openclaw
 ```
 
-### Error messages
-
-All errors include fix suggestions and documentation links:
-
-```
-Ledger unavailable: connection refused
-
-  Hint: Start TigerBeetle with "npx usertrust tb start" or use { dryRun: true } to skip the ledger.
-  Docs: https://usertrust.ai/docs/errors/ledger-unavailable
-```
-
-## Config
-
-Create `.usertrust/usertrust.config.json`:
+Or configure it manually in `openclaw.json`:
 
 ```json
 {
-  "budget": 50000,
-  "tier": "pro",
-  "pii": "block",
-  "circuitBreaker": { "failureThreshold": 5, "resetTimeout": 60000 },
-  "patterns": { "enabled": true },
-  "audit": { "rotation": "daily", "indexLimit": 10000 }
+  "plugins": {
+    "entries": {
+      "usertrust": {
+        "enabled": true,
+        "config": { "budget": 100000, "dryRun": true }
+      }
+    }
+  }
 }
 ```
 
-`defineConfig` is available as a TypeScript type-checking helper for validating config objects in your code. The actual config file must be `usertrust.config.json` (JSON format):
+## Programmatic use
 
 ```typescript
-import { defineConfig } from "usertrust";
+import { createUsertrustPlugin } from "usertrust-openclaw";
 
-// Type-check your config object — useful for programmatic overrides
-const config = defineConfig({
-  budget: 50_000,
-  tier: "pro",
-  pii: "block",
-  circuitBreaker: { failureThreshold: 5, resetTimeout: 60_000 },
-  patterns: { enabled: true },
-  audit: { rotation: "daily", indexLimit: 10_000 },
+const plugin = createUsertrustPlugin({
+  budget: 100_000,   // usertokens for this session
+  dryRun: true,      // try instantly — skips TigerBeetle, keeps policy + audit
 });
 ```
 
-## Features
-
-**Double-entry ledger** — TigerBeetle-backed financial transactions with two-phase lifecycle (PENDING, POST, VOID). Not a counter.
-
-**SHA-256 hash-chained audit** — Every event links to the previous event's hash. Tamper-evident by construction. Append-only JSONL.
-
-**Merkle proofs (RFC 6962)** — Inclusion and consistency proofs for public verifiability. Any third party can verify a specific event existed in the chain.
-
-**Policy engine** — 12 field operators (`eq`, `gt`, `in`, `regex`, etc.) with soft/hard enforcement. Block specific models, cap costs, require approvals.
-
-**PII detection** — Luhn-validated credit card numbers, SSN patterns, email addresses, phone numbers, IPv4 addresses. Block or warn before data leaves your network.
+## How it works
 
-**Circuit breakers** — Per-provider failure isolation. When a provider starts failing, the breaker opens and requests fail fast instead of cascading.
+The plugin hooks OpenClaw's `wrapStreamFn`, so it sits directly on the stream:
 
-**Pattern memory** — Learns optimal model routing from historical prompt-cost-success data. Feeds routing decisions when connected to proxy.
-
-## Why this exists
-
-AI agents operate with financial authority. Every LLM call costs money. Without governance:
-
-- There is no audit trail when an agent spends $500 on a hallucinated loop
-- There is no budget enforcement across multiple concurrent agents
-- There is no way to prove what happened after the fact
-- A race condition between two agents can double-spend the same budget
-
-A counter in a database is not a financial ledger. `usertrust` uses the same double-entry, two-phase commit pattern that banks use. PENDING holds reserve the budget atomically. POST settles. VOID releases. The audit chain is hash-linked and Merkle-provable.
-
-## Comparison
-
-| Feature | usertrust | LiteLLM | Portkey | Langfuse |
-|---------|-----------|---------|---------|----------|
-| Financial ledger | TigerBeetle | Counter | Counter | Observation |
-| Two-phase spend | PENDING/POST/VOID | No | No | No |
-| Hash-chained audit | SHA-256 | No | No | No |
-| Merkle proofs | RFC 6962 | No | No | No |
-| Policy engine | 12 operators | Basic rules | Basic rules | No |
-| PII detection | Luhn + regex | No | No | No |
-| Circuit breakers | Per-provider | Global | Per-provider | No |
-| Offline-first | Local vault | Proxy required | Proxy required | Proxy required |
-| Open source | Apache 2.0 | Apache 2.0 | Proprietary | Apache 2.0 |
-
-## Upgrade path
-
-When you outgrow local mode, point at the proxy. One line:
-
-```typescript
-const client = await trust(new Anthropic(), {
-  proxy: "https://proxy.usertools.ai",
-  key: process.env.USERTOOLS_KEY,
-});
 ```
-
-Same API. Same receipts. Now with cross-agent budget enforcement, centralized audit, and real-time dashboards.
-
-## Verify
-
-Standalone verification with zero dependencies:
-
-```bash
-npx usertrust-verify .usertrust
+agent call → OpenClaw → usertrust wrapStreamFn
+  1. Pre-flight budget check — a call whose estimated cost would exceed the
+     remaining budget is DENIED before it starts (no single-call overshoot).
+  2. PENDING hold reserves the estimate.
+  3. Forward to the real stream, accumulating token usage from each chunk.
+  4. POST settles the actual cost (or VOID on error); an early consumer
+     `break` still settles and releases the hold — no leaked reservation.
+  5. Every call is written to the tamper-evident audit chain.
 ```
 
-```
-Vault integrity: VERIFIED
-Chain length: 847 events
-Merkle root: a3f8c1...d92b
-Hash algorithm: SHA-256
-First event: 2026-03-01T08:12:44.000Z
-Last event: 2026-03-16T14:33:21.000Z
-All hashes: valid (847/847)
-```
+## Config
 
-The verify package has zero runtime dependencies. It reads JSONL, recomputes SHA-256 hashes, and checks the chain. Anyone can verify a vault without trusting the usertrust SDK.
+| Field | Type | Description |
+|-------|------|-------------|
+| `budget` | `number` | Session budget in usertokens (required). |
+| `dryRun` | `boolean` | Skip TigerBeetle; policy gate + audit still run. |
+| `vaultBase` | `string` | Vault location (defaults to the project root). |
+| `proxy` / `proxyKey` | `string` | Point at the hosted proxy for cross-agent budget enforcement. |
 
-## License
+Budget enforcement is **pre-spend**: because a stream's cost isn't known until it finishes, the estimate assumes the model's full output budget, so calls are denied conservatively rather than allowed to overshoot. Size `budget` accordingly.
 
-Apache 2.0
-
----
+## License
 
-UserTrust™ is a trademark of Usertools, Inc.
+Apache 2.0 · UserTrust™ is a trademark of Usertools, Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "usertrust-openclaw",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "usertrust governance plugin for OpenClaw. Budget enforcement, audit trails, and policy gates for every LLM call — zero code changes.",
 	"license": "Apache-2.0",
 	"author": "Usertools, Inc. <hello@usertools.ai> (https://usertrust.ai)",
@@ -11,16 +11,7 @@
 		"directory": "packages/openclaw"
 	},
 	"bugs": "https://github.com/usertools-ai/usertrust/issues",
-	"keywords": [
-		"openclaw",
-		"usertrust",
-		"ai",
-		"governance",
-		"budget",
-		"audit",
-		"llm",
-		"plugin"
-	],
+	"keywords": ["openclaw", "usertrust", "ai", "governance", "budget", "audit", "llm", "plugin"],
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -35,10 +26,7 @@
 		"prepublishOnly": "tsc",
 		"demo": "tsx demo/runaway-agent.ts"
 	},
-	"files": [
-		"dist",
-		"openclaw.plugin.json"
-	],
+	"files": ["dist", "openclaw.plugin.json"],
 	"dependencies": {
 		"usertrust": "*"
 	},