Regent SDK

TypeScript SDK for the Regent — Agentic Communication and Control Protocol. Regent is a protocol for secure, identity-bound communication between autonomous agents and Controllers (wallets), built on Liquid Auth + WebRTC + DIDComm v2.

It is the protocol library: messages, envelopes, signaling, sessions, streaming, file transfer, replay defense, DID resolution. It does not include UI, wallet plumbing, or key management — those live in the Controller (the wallet that approves signing requests) and in agent-side plugins.

Companion projects in this monorepo — each maintains its own README. The SDK README focuses on the SDK and protocol; nothing else.

• packages/regent-plugin-openclaw/ — reference agent-side plugin (OpenClaw channel plugin). Includes its own build & pack instructions.
• vendor/regent/ — reference Controller wallet (RN / Expo). Includes its own architecture, key model, and build lifecycle.
• specs/ — Regent protocol specifications: core, pre-authorized, a2a, discovery.

Status (v0)

| Component | Version | | --- | --- | | @goplausible/regent-sdk | 0.0.8 | | @goplausible/regent-plugin-openclaw | 0.0.111 | | @goplausible/regent-plugin-claude | 0.2.22 | | @goplausible/regent-plugin-codex | 0.2.8 | | regent (reference Controller — download APK) | 1.1.62 | | @goplausible/liquid-auth-cloud (relay, internal) | 1.3.1 |

v0 ships the core protocol over WebRTC with a PlainEnvelope (no DIDComm wrapping yet). DIDComm v2 wrapping is planned post-POC; the port lives in the standalone DIDCOMM-TS repository.

What's working end-to-end: bidirectional text chat, ed25519 sign/verify HITL, seamless reconnect across idle / app-suspend / network-blip / plugin-restart, biometric-gated approval, snake_case wire format aligned with DIDComm v2, the agent badge classifier (sticky liquid → agent mode upgrade on first Regent envelope), Notice envelopes for agent-side status, and chat-limbo grace timeout for survival across user back-out.

Known v0 deviations from the spec (channel label, single-channel transport, to[] optional, regent/Stream* and regent/AttachmentBegin SDK profiles, Approval* not in spec) are noted in the SDK source comments.

Install

npm install @goplausible/regent-sdk
# or
pnpm add @goplausible/regent-sdk
# or
yarn add @goplausible/regent-sdk

Peer requirements:

• Node >= 20 (the package is ESM-only).
• A WebRTC implementation — browser-native RTCPeerConnection / RTCDataChannel in the browser, @roamhq/wrtc (or compatible) in Node.

The SDK does not bundle a WebRTC implementation; you bring your own and pass an RTCDataChannel (or pair of channels) into the session.

Quick start — agent side

Wire the SDK on the agent (Node) side once Liquid Auth has handed you a live RTCDataChannel. The pattern: build channels, build a session, send regent/SigningRequest, await regent/SigningResponse.

import {
  RegentSession,
  attachRegentChannels,
  PlainEnvelope,
  pubkeyToDidKey,
  type SigningRequest,
  type SigningResponse,
} from "@goplausible/regent-sdk";

// 1. Wrap the existing Liquid Auth control channel into Regent's transport shape.
//    v0 is single-channel; pass the peer connection plus the control channel.
const channels = await attachRegentChannels(peerConnection, controlDataChannel);

// 2. Build the session. `from` is the agent's DID, `to` is the wallet's DID
//    (resolved via Liquid Auth attestation).
const agentDid = pubkeyToDidKey(agentEd25519PublicKey);

const session = new RegentSession({
  channels,
  identity: { from: agentDid, to: [walletDid] },
  envelope: new PlainEnvelope(), // default; replace once DIDComm v2 lands
});

// 3. Hook responses before sending the request.
const pending = new Promise<SigningResponse>((resolve, reject) => {
  const off = session.onMessage((msg) => {
    if (msg.type === "regent/SigningResponse" && msg.thid === reqId) {
      off();
      resolve(msg);
    } else if (msg.type === "regent/SigningRejected" && msg.thid === reqId) {
      off();
      reject(new Error((msg.body as { reason: string }).reason));
    }
  });
});

// 4. Send the SigningRequest. The Controller wallet (Regent) prompts the
//    user, gates with biometrics, signs with the right key, and emits the
//    SigningResponse over the same channel.
const reqId = crypto.randomUUID();
const request: SigningRequest = {
  id: reqId,
  type: "regent/SigningRequest",
  from: agentDid,
  to: [walletDid],
  created_time: Math.floor(Date.now() / 1000),
  body: {
    description: "Sign this proposal",
    encoding: "base64",
    payload: btoa("hello world"),
    key_type: "identity",      // 'account' or 'identity'
    display_hint: "text",      // 'text' | 'json' | 'hex'
  },
};
await session.send(request);

const response = await pending;
console.log("signature:", response.body.signature);
console.log("public key:", response.body.public_key);

Quick start — Controller (wallet) side

Most consumers of the SDK on the wallet side won't construct a session manually — they'll either use Regent as-is or implement a WithRegent extension. But for reference, the parsing path looks like this:

import { validateMessage, type RegentMessage } from "@goplausible/regent-sdk";

controlChannel.addEventListener("message", async (ev) => {
  if (typeof ev.data !== "string") return;
  let parsed: unknown;
  try {
    parsed = JSON.parse(ev.data);
  } catch {
    return; // not a Regent envelope; treat as chat text
  }
  if (!validateMessage(parsed)) return;
  const msg: RegentMessage = parsed;
  switch (msg.type) {
    case "regent/SigningRequest":
      await handleSigningRequest(msg);
      break;
    case "regent/Notice":
      surfaceNotice(msg);
      break;
    // ... other types
  }
});

For a complete reference implementation see Regent's useConnection hook which handles the full lifecycle: incoming envelope dispatch, sticky mode-upgrade, signing-modal flow, biometric gate, notice banners, and reconnect resilience.

Modules & exported API

The SDK is intentionally small and tree-shakeable. Top-level exports from @goplausible/regent-sdk:

| Module | Key exports | Purpose | |---|---|---| | identity | pubkeyToDidKey, algorandAddressToDidKey, DidKeyResolver, DidWebResolver, Did, DidDocument, DidResolver | DID derivation & resolution (did:key, did:web). | | transport | attachRegentChannels, RegentSignaling, RegentChannels, CONTROL_CHANNEL_LABEL, DATA_CHANNEL_LABEL, FILE_CHUNK_SIZE | Wraps Liquid Auth signaling + DataChannels into Regent's RegentChannels shape. | | envelope | PlainEnvelope, Envelope, PackedEnvelope | Pluggable envelope layer. v0 uses PlainEnvelope; DIDComm v2 lands later as a drop-in. | | messages | RegentMessage, SigningRequest, SigningResponse, SigningRejected, StreamRequest, StreamResponse, StreamChunk, AttachmentBegin, AttachmentRef, Notice, validateMessage | Wire-message types + Zod-free runtime validator. | | session | RegentSession, RegentSessionOptions, SessionIdentity, MessageHandler, StreamEventHandler | High-level session: send/receive Regent messages, manage streams, attachments, replay dedupe. | | streaming | StreamReader, StreamWriter, StreamEvent, StreamUsage | Chunked streaming primitives used internally by RegentSession.writeStreamChunk/onStream. | | files | FileSender, FileReceiver, ReceivedFile | Attachment send/receive over the regent-data binary channel (cold-path in v0). | | replay | ReplayDedupe | LRU dedupe keyed by (channel, message id). Used by default by RegentSession. |

Wire profile (v0 — single-channel)

v0 runs single-channel: Regent messages travel as JSON text frames on the existing liquid DataChannel from liquid-auth-js. The optional second regent-data binary channel for file transfer is not wired in v0 (machinery exists in src/files/ but is cold-path).

| Channel | Label on the wire | Type | Purpose | | --- | --- | --- | --- | | Control | liquid | text | All Regent protocol messages (signing trio + lenient plain text), reliable + ordered. | | Data | regent-data | binary | Reserved; not created in v0. File chunks when wired. |

Spec target label is regent-v1 (see specs/regent.md § WebRTC DataChannel Transport). Switching to regent-v1 requires a coordinated SDK + plugin + Controller release; tracked as a v0 deviation.

Mode: lenient text on the control channel (Path B). Plain text from the wallet is treated as user chat; JSON frames are parsed as Regent envelopes (regent/SigningRequest / regent/SigningResponse / regent/SigningRejected / regent/Notice). Live duplex audio and video are out of scope for v0.

SDK layout

src/
├── identity/    DID derivation + resolution (did:key, did:web)
├── transport/   RegentSignaling + RegentChannels (wraps Liquid Auth DataChannels)
├── envelope/    PlainEnvelope (default); DIDComm v2 later
├── messages/    Wire-message types + runtime validator
├── streaming/   StreamReader / StreamWriter
├── files/       FileSender / FileReceiver (cold-path in v0)
├── replay/      Per-channel replay dedupe
└── session/     RegentSession — high-level send/receive

For the OpenClaw plugin source, see packages/regent-plugin-openclaw/. For the Controller reference, see vendor/regent/. Both have their own READMEs.

Build & test

npm install
npm run build       # tsc → dist/
npm test            # vitest run
npm run typecheck   # tsc --noEmit

Pack a fresh SDK tarball:

# 1. Bump version in package.json + package-lock.json.
# 2. Build, then pack.
npm run build
npm pack --pack-destination /tmp
# → /tmp/goplausible-regent-sdk-<version>.tgz

Recently shipped

A short log of what landed in the SDK + ecosystem since v0 first ran end-to-end. Detailed history is in commit logs and the per-component changelogs.

• Sticky liquid → agent mode upgrade on first structured envelope — wallets can classify the badge before the first Regent message even arrives if the agent emits a session.opened Notice on bind.
• regent/Notice envelope wired end-to-end — agent emits curated error/warn/info; Controller surfaces banners + persists to per-connection logs with FIFO rotation.
• agent_type self-identification lifted from any nesting (root / body / metadata, snake or camel) — free-form so new agent authors slot in without coordinating with the Controller.
• Lenient text mode (Path B) on the control channel so non-Regent chat from the wallet doesn't error out the Regent parser.
• Replay dedupe scoped per channel label (liquid / regent-data) so future second-channel addition doesn't cross-pollinate.
• OpenClaw plugin v0.0.39 — depends on SDK v0.0.8 via npm (no longer bundles). Sign tool exposes both display_hint (UX preview, spec-stable text/json/hex) and sig_hint (new spec field — explicit cryptographic-operation selector with 9 values: raw-ed25519, raw-secp256k1, message-algorand, message-evm, message-solana, typed-data-evm, transaction-{algorand,evm,solana}). Ten verifier tools — one for every sig_hint value, names mapped 1:1 — including the three transaction verifiers (algosdk / viem / @solana/web3.js-backed). Proactive session.opened Notice + agent_type: "openclaw" on every envelope.

SDK / protocol TODO

Items in flight on the SDK and spec side. Regent-side and Controller-UX items live in the Regent README.

• DIDComm v2 envelope — v0 ships PlainEnvelope; the spec target is full DIDComm v2 wrapping (from always present, to[] required, replay defense, audit, forward routing). The Envelope interface is the swap-in point. Plan parked at vendor/didcomm-ts/PORT_PLAN.md.
• TypeScript DIDComm port from vendor/didcomm-rust (SICPA reference). No reliable pure-TS DIDComm SDK exists today; the port becomes @goplausible/didcomm and unblocks the DIDComm v2 envelope above.
• regent/AttachmentBegin + regent-data binary channel — file-transfer machinery exists in src/files/ but is cold-path. Wire the second negotiated DataChannel on both peers, add the Regent-side recording UX, ship voice messages and file attachments for chats.
• Discovery spec implementation — spec drafted at specs/regent-ext-discovery.md; SDK + plugin code still to come.
• A2A extension — spec drafted at specs/regent-ext-a2a.md; agent-to-agent communication primitives.
• AP2 mandates — generation + verification of agent payment mandates; envelope type and helper functions.
• MPP session spec + matching SDK primitives — the Multi-Party Payment session work is gated on the spec landing first.
• ERC-8004 support — agent-side, for Regent sessions that involve EVM signing.
• Claude plugin — sibling to OpenClaw under packages/. Top-level agent_type: "claude" is already wired into Regent's badge classifier; the plugin itself is open.
• Codex plugin — same shape as Claude, for the Codex runtime. Third reference plugin alongside OpenClaw + Claude.
• regent CLI — auto-injects the Regent toolset into an existing agent runtime: detects the host framework, installs + configures the matching plugin, scaffolds the user-journey config, and provides the agent with signing-request / verification-request tooling. Goal: drop Regent into an existing agent in one command.

SDK / protocol ROADMAP

Bigger arcs, not strictly ordered:

• Channel-label cutover to regent-v1. Coordinated SDK + plugin + Controller release that flips the control channel label from liquid to the spec-target regent-v1. Tracked as a v0 deviation.
• Second-channel (regent-data) negotiation turned on by default once @roamhq/wrtc renegotiation interference is verified resolved — unblocks live file transfer and large attachments end-to-end.
• Notice as the agent-side observability stream. Today four sinks (banner, log, activity, badge counter). Future: structured fields per code, per-tenant filtering, severity-aware retry/backoff hints carried in the envelope.
• Pluggable session policies. Per-session signing-key policy ("this agent can only request key_type: identity"), per-agent rate limits, time-bound capability tokens — all enforced at the SDK boundary so Controllers don't have to reimplement the logic.
• Test-vector parity with the Rust DIDComm reference — the TS port lands with a vector suite that round-trips against didcomm-rust outputs.

Contributing

This SDK is part of GoPlausible. Issues, PRs, and protocol-spec discussions welcome — see specs/ for the wire formats.

License

Apache-2.0