@agentvault/agentvault 0.17.0 → 0.17.2

package/README.md

@@ -1,119 +1,274 @@
 # @agentvault/agentvault
 
-The security infrastructure layer for AI agents — cryptographic identity, earned trust, and Signal-grade encrypted communications natively integrated with OpenClaw.
+The security infrastructure layer for AI agents — cryptographic identity, earned trust, and Signal-grade encrypted communications natively integrated with [OpenClaw](https://openclaw.ai).
 
-Connect your agent to its owner with XChaCha20-Poly1305 encryption, Double Ratchet forward secrecy, and W3C Decentralized Identifiers (DIDs).
+Connect your agent to its owner with XChaCha20-Poly1305 encryption, Double Ratchet forward secrecy, and W3C Decentralized Identifiers (DIDs). No plaintext ever touches the server.
 
-## What's New in v0.14.30 (Gen2)
+## What's New in v0.17.0
 
-* **OpenClaw Native Plugin:** AgentVault now integrates directly into OpenClaw as a first-class channel (`agentvault`).
-* **W3C Decentralized Identifiers (DIDs):** Agents are now addressed using cryptographic identities (`did:hub:<address>`).
-* **Room Cryptography & Sender Keys:** Advanced group chat encryption using sender key distribution, automatic force rekeying, and robust ratchet state snapshot/restore mechanisms.
-* **Trust Scoring & Telemetry:** Native OpenTelemetry (OTel) auto-instrumentation to compute real-time trust scores.
-* **Skill Permission Tokens (SPTs):** Support for explicit-deny authorization and cryptographic capability access grants.
+* **Policy Enforcer:** 5-stage policy pipeline (Parse → Validate → Enforce → Log → Report) with tool blocklists, model routing rules, and telemetry emission.
+* **SKILL.md `agentVault` Namespace:** Extended skill metadata supporting certification tiers, integrity declarations, runtime capabilities, and model routing.
+* **Unified Delivery Protocol:** Single `deliver()` dispatcher for all outbound messages — text, decisions, approvals, policy alerts, and artifacts.
+* **20 OTel Span Types:** Full observability with `av.*`-prefixed spans for policy violations, decisions, A2A, scans, rooms, trust, and more.
+* **W3C TraceContext:** All telemetry spans carry `traceparent` and `tracestate` for cross-agent trace correlation.
 
----
-
-## Installation & Quick Start
+## Installation
 
-### 1. OpenClaw Channel Integration (Recommended)
-
-To install AgentVault globally as an OpenClaw channel plugin:
+### OpenClaw Plugin (Recommended)
 
 ```bash
-# Using pnpm (adjust path to your global installation)
-PNPM_HOME=~/Library/pnpm /opt/homebrew/bin/pnpm add -g @agentvault/agentvault@latest
+openclaw plugins install @agentvault/agentvault
 ```
 
-After installation, configure the channel with your invite token from the AgentVault dashboard:
+Then enroll your agent with an invite token from the [AgentVault dashboard](https://app.agentvault.chat):
 
 ```bash
 npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
 ```
 
-⚠️ **CRITICAL WARNING FOR UPGRADES:**
-> There is currently a known bug in `setup.js` where running `setup` on an already enrolled agent will wipe the existing account configuration. **Always back up your `agentvault.json` and `agentvault-data` directories before updating the plugin or re-running setup.**
-
-### 2. Standalone CLI Usage
-
-If you are not using OpenClaw, you can run AgentVault as a standalone interactive CLI:
+### Standalone CLI
 
 ```bash
 npx @agentvault/agentvault setup --token=YOUR_INVITE_TOKEN
 npx @agentvault/agentvault
 ```
 
-The CLI will:
-1. Generate an Ed25519 identity keypair
-2. Enroll your agent with the server (anchoring a `did:hub` identity)
-3. Wait for owner approval
-4. Establish an end-to-end encrypted channel
+The CLI will generate an Ed25519 identity keypair, enroll with the server (anchoring a `did:hub` identity), wait for owner approval, and establish an E2E encrypted channel.
 
----
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `setup --token=TOKEN` | Enroll a new agent with an invite token |
+| `create --name=NAME` | Create a new agent account in OpenClaw |
+| `send --text="..."` | Send a message through the gateway |
+| `status` | Check gateway connection and agent status |
+| `skills` | List loaded skills from SKILL.md files |
+| `doctor [--fix]` | Diagnose and fix LaunchAgent / gateway issues |
+| `version` | Print the installed version |
 
-## Programmatic SDK Integration
+## Programmatic Usage
 
-You can easily integrate AgentVault directly into custom Node.js/TypeScript agent architectures.
+### SecureChannel
 
-```ts
+The core class for establishing an E2E encrypted channel between your agent and its owner.
+
+```typescript
 import { SecureChannel } from "@agentvault/agentvault";
 
 const channel = new SecureChannel({
   inviteToken: process.env.AGENTVAULT_INVITE_TOKEN,
   dataDir: "./agentvault-data",
   apiUrl: "https://api.agentvault.chat",
-  agentName: "My Custom Agent",
+  agentName: "My Agent",
 });
 
 channel.on("message", (text, metadata) => {
-  console.log(`[AgentVault] Received: ${text}`);
-  // Execute agent logic, then send response:
-  channel.send(`Task complete. Result: ${text}`);
+  console.log(`Owner says: ${text}`);
+  console.log(`Type: ${metadata.messageType}`);
 });
 
 channel.on("ready", () => {
-  console.log(`Secure channel established! Routing address: did:hub:${channel.deviceId}`);
+  console.log(`Secure channel established: did:hub:${channel.deviceId}`);
 });
 
 await channel.start();
 ```
 
-### Advanced: Telemetry & OTel
-To enable behavioral trust scoring, configure the telemetry exporter:
+### Gateway Send Helpers
+
+Send messages from your agent code without managing the channel directly:
+
+```typescript
+import { sendToOwner, sendToRoom, sendToTarget, listTargets } from "@agentvault/agentvault";
+
+// Send to the agent owner
+await sendToOwner("Task complete — 3 files processed");
+
+// Send to a multi-agent room
+await sendToRoom("room_abc123", "Ready for review");
+
+// Send to any target (auto-resolves owner, room, or A2A)
+await sendToTarget("did:hub:other_agent", "Handoff data");
+
+// List available targets
+const targets = await listTargets();
+```
+
+### Structured Messages
 
-```ts
-// Telemetry is automatically routed through the established E2E channel
-channel.enableTelemetry({
-  serviceName: "my-custom-agent",
-  exportIntervalMs: 5000
+```typescript
+import { sendDecisionToOwner } from "@agentvault/agentvault";
+
+// Decision request — ask the owner to choose
+await sendDecisionToOwner({
+  question: "Which database should I use?",
+  options: [
+    { label: "PostgreSQL", value: "postgres" },
+    { label: "SQLite", value: "sqlite" },
+  ],
+  urgency: "medium",
 });
 ```
 
+All 8 message types are supported: `text`, `decision_request`, `decision_response`, `approval_request`, `approval_response`, `policy_alert`, `artifact_share`.
+
+### Skill Management
+
+Define skills using SKILL.md frontmatter:
+
+```markdown
+---
+name: code-review
+version: "1.0.0"
+description: Reviews code for issues
+tags: [code-review, typescript]
+sla:
+  p95_latency_ms: 5000
+  max_error_rate: 0.05
+schema:
+  type: object
+  properties:
+    code:
+      type: string
+  required: [code]
+agentVault:
+  certification: certified
+  integrity:
+    algorithm: XChaCha20-Poly1305
+    hashChain: SHA-256
+  requiredPolicies: ["network: agentvault"]
+  runtime:
+    capabilities: [file.read, web.fetch]
+    forbidden: [shell.exec]
+  model:
+    allowed: [gpt-4, claude-sonnet-4-20250514]
+    default: claude-sonnet-4-20250514
 ---
+# Code Review Skill
 
-## Security Architecture
+Review the provided code for bugs, security issues, and style violations...
+```
 
-AgentVault is a **zero-knowledge** platform. The server only routes ciphertext and NEVER sees your data in plaintext.
+Load and use skills programmatically:
 
-* **Identity:** Ed25519 dual-key model (Owner Key + Operational Key) linked to a `did:hub` identifier.
-* **Encryption:** XChaCha20-Poly1305 symmetric encryption with 192-bit nonces (eliminating nonce reuse risk).
-* **Forward Secrecy:** Double Ratchet protocol and X3DH key agreement. Old keys are mathematically destroyed.
-* **Group Cryptography:** Sender key distribution with automatic force rekeying (`room_message_sk`) for multi-agent rooms.
-* **Audit Trails:** All operations are chained using BLAKE2b hashes and W3C TraceContext traceparents.
+```typescript
+import { parseSkillMd, loadSkillsFromDirectory, invokeSkill } from "@agentvault/agentvault";
 
-## Webhook Notifications
+// Load all SKILL.md files from a directory
+const manifest = await loadSkillsFromDirectory("./skills");
 
-Enable HTTP POST webhooks when a new message arrives for offline-capable agents:
+// Invoke a skill with policy enforcement
+const result = await invokeSkill("code-review", {
+  args: { code: "function foo() { eval(input); }" },
+});
+```
 
-```ts
-const channel = new SecureChannel({
-  // ...
-  webhookUrl: "https://your-server.com/webhook/agentvault",
+### Policy Enforcement
+
+The PolicyEnforcer validates skill invocations against a 5-stage pipeline:
+
+```typescript
+import { PolicyEnforcer } from "@agentvault/agentvault";
+
+const enforcer = new PolicyEnforcer();
+
+// Register a skill with its policy constraints
+enforcer.registerSkill({
+  name: "code-review",
+  toolsAllowed: ["file.read"],
+  toolsDenied: ["shell.exec", "network.raw"],
+  modelRouting: { allowed: ["gpt-4", "claude-sonnet-4-20250514"] },
+});
+
+// Evaluate before execution
+const result = enforcer.evaluate({
+  skillName: "code-review",
+  toolName: "shell.exec",
+  model: "gpt-4",
 });
+
+if (!result.allowed) {
+  console.log("Blocked:", result.violations);
+  // [{ ruleId: "tool_deny", scope: "tool", message: "shell.exec is forbidden" }]
+}
+
+// Get aggregate metrics
+const metrics = enforcer.getMetrics();
+// { totalEvaluations: 42, totalBlocks: 3, bySkill: {...}, byRule: {...} }
 ```
-*Verify incoming webhooks using the HMAC-SHA256 signature provided in the `X-AgentVault-Signature` header.*
 
----
+### MCP Server (Embedded)
+
+Expose your agent's skills as MCP tools:
+
+```typescript
+import { AgentVaultMcpServer } from "@agentvault/agentvault";
+
+const mcpServer = new AgentVaultMcpServer({
+  skills: manifest.skills,
+  channel,          // SecureChannel instance for message relay
+  enforcer,         // PolicyEnforcer for pre-execution checks
+});
+```
+
+### Telemetry
+
+The plugin auto-instruments all message operations with OTel-shaped telemetry spans. Spans are exported to `https://api.agentvault.chat/api/v1/otel/push` and feed the trust scoring engine and observability dashboard.
+
+```typescript
+import { wrapSkillExecution, reportSkillInvocation } from "@agentvault/agentvault";
+
+// Wrap a skill execution to auto-emit spans
+const result = await wrapSkillExecution("code-review", async () => {
+  // Your skill logic here
+  return { issues: 3 };
+});
+```
+
+## OpenClaw Integration
+
+When installed as an OpenClaw plugin, AgentVault registers as the `agentvault` channel:
+
+```json
+{
+  "channels": {
+    "agentvault": {
+      "accountId": "your-agent-account-id"
+    }
+  }
+}
+```
+
+The plugin hooks into OpenClaw's lifecycle:
+
+- **Channel gateway** — routes inbound/outbound messages through the E2E encrypted channel
+- **Heartbeat wake** — keeps the agent alive via OpenClaw's heartbeat system
+- **Agent events** — listens for session start/end and transcript updates
+- **Managed HTTP routes** — `/send`, `/status`, `/targets`, `/action`, `/decision`
+- **MCP serving** — exposes skills as MCP tools via `/mcp` route
+
+## Security Architecture
+
+AgentVault is a **zero-knowledge** platform. The server routes ciphertext and NEVER sees plaintext.
+
+| Layer | Technology |
+|-------|-----------|
+| Identity | Ed25519 keypairs linked to `did:hub` identifiers |
+| Encryption | XChaCha20-Poly1305 with 192-bit nonces |
+| Forward Secrecy | Double Ratchet protocol + X3DH key agreement |
+| Group Crypto | Sender Key distribution with automatic force rekeying |
+| Audit | BLAKE2b hash-chained entries with W3C TraceContext |
+| Policy | 5-stage pipeline: Parse → Validate → Enforce → Log → Report |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@agentvault/sdk`](https://www.npmjs.com/package/@agentvault/sdk) | SDK for third-party agent integration (API key auth + E2E) |
+| [`@agentvault/mcp-server`](https://www.npmjs.com/package/@agentvault/mcp-server) | Standalone MCP server for any MCP-compatible host |
+| [`@agentvault/crypto`](https://www.npmjs.com/package/@agentvault/crypto) | Cryptographic primitives (Double Ratchet, X3DH, XChaCha20, telemetry) |
+| [`@agentvault/verify`](https://www.npmjs.com/package/@agentvault/verify) | Lightweight agent verification SDK |
 
 ## License