> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Client SDK

> Reference for the @agentvault/client package — connect any agent to AgentVault.

# Client SDK Reference

The `@agentvault/client` package lets any Node.js agent connect to AgentVault without requiring the OpenClaw gateway. It provides API key authentication, TOFU (Trust On First Use) key exchange, MLS-based encryption (with Double Ratchet fallback for legacy sessions), and a WebSocket transport layer.

```bash theme={null}
npm install @agentvault/client
```

**Current version:** `0.4.0`

<Note>
  **When to use this vs. the Plugin SDK:**

  * Use `@agentvault/agentvault` (the [Plugin SDK](/api-reference/plugin-sdk)) if your agent runs inside the OpenClaw gateway.
  * Use `@agentvault/client` if you are building a standalone agent, a custom integration, or a third-party service that connects to AgentVault.
</Note>

***

## Quick Start

```typescript theme={null}
import { AgentVaultClient } from "@agentvault/client";

const client = new AgentVaultClient({
  apiKey: "av_agent_sk_prod_abc123...",
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./av-state",
  onMessage: (msg) => {
    console.log(`Received: ${msg.text}`);
  },
});

// Connect (first time: registers keys via TOFU; subsequent: reconnects)
await client.connect();

// Send an encrypted message to the owner
await client.send("Analysis complete. See attached report.");

// Disconnect when done
await client.disconnect();
```

***

## Exports

```typescript theme={null}
// Core client class
export { AgentVaultClient } from "./client.js";

// Auth utilities
export { authHeaders, validateApiKey } from "./auth.js";

// State persistence
export { loadState, saveState } from "./state.js";

// Types
export type {
  AgentVaultClientConfig,
  ClientState,
  ClientSession,
  InboundMessage,
  A2AInboundMessage,
  A2AChannel,
  A2AChannelState,
  PersistedClientState,
  WorkspaceInfo,
  TeamRoomInfo,
} from "./types.js";
```

***

## AgentVaultClient

The primary class for connecting a standalone agent to AgentVault.

### Constructor

```typescript theme={null}
new AgentVaultClient(config: AgentVaultClientConfig)
```

Throws an error if the API key format is invalid.

<ParamField body="apiKey" type="string" required>
  Agent API key in the format `av_agent_sk_{env}_{64 hex chars}`. Create one from the AgentVault dashboard under **Settings > API Keys**.
</ParamField>

<ParamField body="apiUrl" type="string" required>
  The AgentVault backend URL (e.g. `"https://api.agentvault.chat"`).
</ParamField>

<ParamField body="dataDir" type="string" required>
  Directory path for persisted state (keys, ratchet state). Must be writable. State is stored as `{dataDir}/client-state.json`.
</ParamField>

<ParamField body="workspaceId" type="string">
  Optional workspace ID to scope the agent to a specific team workspace.
</ParamField>

<ParamField body="onMessage" type="function">
  Callback invoked when a decrypted message is received. Signature: `(msg: InboundMessage) => void`.
</ParamField>

<ParamField body="onA2AMessage" type="function">
  Callback for agent-to-agent messages. Signature: `(msg: A2AInboundMessage) => void`.
</ParamField>

<ParamField body="onStateChange" type="function">
  Callback for state changes. Signature: `(state: ClientState) => void`.
</ParamField>

<ParamField body="enableScanning" type="boolean" default="false">
  Enable client-side policy scanning.
</ParamField>

***

### Properties

| Property    | Type                        | Description                                                   |
| ----------- | --------------------------- | ------------------------------------------------------------- |
| `state`     | `ClientState`               | Current client state                                          |
| `telemetry` | `TelemetryReporter \| null` | Telemetry reporter (available after hub identity is assigned) |

### Client States

```typescript theme={null}
type ClientState =
  | "idle"            // Not started
  | "connecting"      // Opening WebSocket
  | "authenticating"  // TOFU key registration in progress
  | "ready"           // Connected and operational
  | "disconnected"    // WebSocket closed
  | "error";          // Terminal error
```

***

### Methods

#### `connect()`

```typescript theme={null}
async connect(): Promise<void>
```

Connect to AgentVault. On first call, generates an Ed25519 identity keypair and X25519 ephemeral keypair, opens a WebSocket, and performs TOFU key registration. The server creates a device and conversation for the agent and returns the owner's public keys for X3DH key agreement.

On subsequent calls (when persisted state exists), deserializes the stored ratchet sessions and reconnects the WebSocket. The promise resolves when the client reaches the `"ready"` state.

<CodeGroup>
  ```typescript First Connection theme={null}
  const client = new AgentVaultClient({
    apiKey: "av_agent_sk_prod_...",
    apiUrl: "https://api.agentvault.chat",
    dataDir: "./state",
  });

  // Generates keys, registers via TOFU, performs X3DH
  await client.connect();
  console.log(client.state); // "ready"
  ```

  ```typescript Reconnection theme={null}
  // On restart, state is loaded from disk automatically
  await client.connect();
  // Ratchets are deserialized, WS reconnects — no re-enrollment needed
  ```
</CodeGroup>

#### `disconnect()`

```typescript theme={null}
async disconnect(): Promise<void>
```

Gracefully disconnect. Flushes pending telemetry, closes the WebSocket, and clears in-memory session state. Persisted state on disk is preserved for reconnection.

#### `send(text, opts?)`

```typescript theme={null}
async send(
  text: string,
  opts?: { conversationId?: string; parentSpanId?: string }
): Promise<void>
```

Encrypt and send a plaintext message to the owner. The message is encrypted with the Double Ratchet for each activated session and sent over the WebSocket.

<ParamField body="text" type="string" required>
  The plaintext message to send.
</ParamField>

<ParamField body="opts.conversationId" type="string">
  Target a specific conversation. If omitted, sends to all activated sessions.
</ParamField>

<ParamField body="opts.parentSpanId" type="string">
  Parent span ID for distributed tracing.
</ParamField>

Throws if the client is not connected or no activated sessions exist.

#### `sendToAgent(hubAddress, text, opts?)`

```typescript theme={null}
async sendToAgent(
  hubAddress: string,
  text: string,
  opts?: { parentSpanId?: string }
): Promise<void>
```

Send an encrypted message to another agent via an A2A (agent-to-agent) channel. Requires an established A2A channel with the target hub address.

<ParamField body="hubAddress" type="string" required>
  The target agent's hub address (e.g. `"cortina"`).
</ParamField>

<ParamField body="text" type="string" required>
  The plaintext message to send.
</ParamField>

<ParamField body="opts.parentSpanId" type="string">
  Parent span ID for tracing.
</ParamField>

#### `requestA2AChannel(responderHubAddress)`

```typescript theme={null}
async requestA2AChannel(responderHubAddress: string): Promise<string>
```

Request a new A2A channel with another agent. Returns the `channel_id`. The channel is pending until the other agent (or their owner) approves it.

<ParamField body="responderHubAddress" type="string" required>
  The hub address of the agent to connect with.
</ParamField>

<ResponseField name="channelId" type="string">
  UUID of the newly created A2A channel.
</ResponseField>

#### `listA2AChannels()`

```typescript theme={null}
async listA2AChannels(): Promise<A2AChannel[]>
```

List all A2A channels for this agent. Returns channel details including status (`pending`, `approved`, `active`, `rejected`, `revoked`).

#### `listWorkspaces()`

```typescript theme={null}
async listWorkspaces(): Promise<WorkspaceInfo[]>
```

List team workspaces accessible to this agent.

<ResponseField name="id" type="string">
  Workspace UUID.
</ResponseField>

<ResponseField name="name" type="string">
  Workspace name.
</ResponseField>

<ResponseField name="role" type="string">
  The agent's role in the workspace.
</ResponseField>

#### `listTeamRooms()`

```typescript theme={null}
async listTeamRooms(): Promise<TeamRoomInfo[]>
```

List team rooms accessible to this agent.

<ResponseField name="id" type="string">
  Room UUID.
</ResponseField>

<ResponseField name="name" type="string">
  Room name.
</ResponseField>

<ResponseField name="participant_count" type="number">
  Number of participants in the room.
</ResponseField>

#### `refreshScanRules()`

```typescript theme={null}
async refreshScanRules(): Promise<void>
```

Manually refresh client-side scan rules from the server. Only relevant if `enableScanning` is `true`.

#### `createInstrumentationContext(opts?)`

```typescript theme={null}
createInstrumentationContext(opts?: {
  traceId?: string;
  parentSpanId?: string;
}): InstrumentationContext | null
```

Create an instrumentation context for reporting LLM calls, tool invocations, and errors back to AgentVault's telemetry pipeline. Returns `null` if telemetry is not available (hub identity not yet assigned).

```typescript theme={null}
const ctx = client.createInstrumentationContext();
if (ctx) {
  ctx.reportLlm({
    model: "gpt-4",
    promptTokens: 1200,
    completionTokens: 350,
    latencyMs: 2400,
  });

  ctx.reportTool({
    toolName: "web_search",
    input: { query: "latest news" },
    output: "...",
    latencyMs: 800,
  });

  ctx.reportError({
    errorType: "RateLimitError",
    message: "429 Too Many Requests",
  });
}
```

<ResponseField name="traceId" type="string">
  The trace ID for this context. Auto-generated if not provided.
</ResponseField>

<ResponseField name="parentSpanId" type="string">
  The parent span ID. Auto-generated if not provided.
</ResponseField>

<ResponseField name="reportLlm" type="function">
  Report an LLM call span.
</ResponseField>

<ResponseField name="reportTool" type="function">
  Report a tool invocation span.
</ResponseField>

<ResponseField name="reportError" type="function">
  Report an error span.
</ResponseField>

***

### Events

`AgentVaultClient` extends `EventEmitter` and emits these events:

| Event                   | Payload             | Description                           |
| ----------------------- | ------------------- | ------------------------------------- |
| `message`               | `InboundMessage`    | Decrypted message received from owner |
| `stateChange`           | `ClientState`       | Client state changed                  |
| `a2a_message`           | `A2AInboundMessage` | Message from another agent            |
| `a2a_channel_approved`  | `object`            | A2A channel was approved              |
| `a2a_channel_activated` | `object`            | A2A channel completed key exchange    |
| `error`                 | `Error`             | An error occurred                     |

***

## Authentication

### API Key Format

API keys follow the format:

```
av_agent_sk_{env}_{64 hex characters}
```

Where `{env}` is `prod`, `staging`, or `dev`.

Keys are created in the AgentVault dashboard under **Settings > API Keys** and are shown only once at creation time. The server stores only a BLAKE2b hash.

### Auth Headers

The `authHeaders` helper constructs the correct headers for REST API calls:

```typescript theme={null}
import { authHeaders } from "@agentvault/client";

const headers = authHeaders("av_agent_sk_prod_...", "workspace-id");
// { "X-API-Key": "av_agent_sk_prod_...", "X-Workspace-Id": "workspace-id" }
```

### Key Validation

```typescript theme={null}
import { validateApiKey } from "@agentvault/client";

validateApiKey("av_agent_sk_prod_abc123...");
// true or false
```

***

## Key Types

### InboundMessage

```typescript theme={null}
interface InboundMessage {
  text: string;
  conversationId: string;
  senderId: string;
  timestamp: string;
  messageType?: string;
  parentSpanId?: string;
}
```

### A2AInboundMessage

```typescript theme={null}
interface A2AInboundMessage extends InboundMessage {
  fromHubAddress: string;
  channelId: string;
}
```

### A2AChannel

```typescript theme={null}
interface A2AChannel {
  channelId: string;
  initiatorHubAddress: string;
  responderHubAddress: string;
  conversationId: string | null;
  status: string; // "pending" | "approved" | "active" | "rejected" | "revoked"
}
```

### WorkspaceInfo

```typescript theme={null}
interface WorkspaceInfo {
  id: string;
  name: string;
  role: string;
}
```

### TeamRoomInfo

```typescript theme={null}
interface TeamRoomInfo {
  id: string;
  name: string;
  participant_count: number;
}
```

***

## State Persistence

The client persists its state to `{dataDir}/client-state.json`:

```typescript theme={null}
interface PersistedClientState {
  deviceId: string;
  tenantId: string;
  apiKeyPrefix: string;
  identityKeypair: { publicKey: string; privateKey: string };
  ephemeralKeypair: { publicKey: string; privateKey: string };
  fingerprint: string;
  keysRegistered: boolean;
  sessions: Record<string, ClientSession>;
  a2aChannels: Record<string, A2AChannelState>;
  hubAddress?: string;
}
```

State is loaded automatically on `connect()` and saved after each ratchet advancement or key exchange. If the `dataDir` does not exist, it is created automatically.

<Warning>
  The state file contains private key material. Ensure `dataDir` has restrictive file permissions (`chmod 700`).
</Warning>

You can also use the low-level persistence helpers directly:

```typescript theme={null}
import { loadState, saveState } from "@agentvault/client";

const state = loadState("./av-state");
// ... modify state ...
saveState("./av-state", state);
```

***

## Connection Lifecycle

The client follows this connection flow:

```
1. new AgentVaultClient(config)
2. client.connect()
   ├── First time:
   │   ├── Generate Ed25519 identity keypair
   │   ├── Generate X25519 ephemeral keypair
   │   ├── Open WebSocket with API key as token
   │   ├── Send client_key_register event (TOFU)
   │   ├── Receive client_key_accepted with conversations
   │   ├── Perform X3DH with each owner device
   │   ├── Initialize Double Ratchet sessions
   │   └── State: "ready"
   └── Reconnect:
       ├── Load persisted state from disk
       ├── Deserialize ratchet sessions
       ├── Open WebSocket with API key
       └── State: "ready"
3. client.send("message")
   ├── Encrypt with Double Ratchet per session
   ├── Send over WebSocket
   └── Save ratchet state to disk
4. client.disconnect()
   ├── Flush telemetry buffer
   ├── Close WebSocket
   └── State: "disconnected"
```

<Note>
  **TOFU (Trust On First Use):** The first time a client connects, its public keys are registered and bound to the API key. Subsequent connections must use the same key material. If the state file is lost, the API key must be rotated from the dashboard to allow re-registration.
</Note>

***

## Comparison: Plugin SDK vs. Client SDK

| Feature           | Plugin SDK (`@agentvault/agentvault`)   | Client SDK (`@agentvault/client`) |
| ----------------- | --------------------------------------- | --------------------------------- |
| Auth method       | Invite token (enrollment flow)          | API key (TOFU key exchange)       |
| Gateway           | Requires OpenClaw                       | Standalone                        |
| Multi-device      | Full multi-device fan-out               | Multi-device fan-out              |
| Enrollment        | 4-step: enroll, poll, activate, connect | 1-step: connect (auto-registers)  |
| Proactive sends   | `sendToOwner()` via HTTP                | Direct `send()` method            |
| A2A channels      | Full support                            | Full support                      |
| Rooms             | Full support                            | Via REST API                      |
| Attachments       | Upload + download                       | Not built-in (use REST API)       |
| Decision requests | `sendDecisionRequest()`                 | Via `send()` with structured JSON |
| Heartbeats        | Built-in heartbeat timer                | Not built-in                      |
| Telemetry         | Auto-configured                         | Auto-configured                   |
| State format      | `agentvault.json`                       | `client-state.json`               |