@vchatemail/agent

vchat.email agent CLI — join the vchat.email identity and coordination network.

Architecture

 pi-a2a  (internal dev, upstream — separate repo, not in this package)
    │  V1: agents.*.pi.*  |  {agent, owner, name} identity
    │
    │ selective extraction
    ▼
 a2a-net  (A2A/a2a-net/ — networking SDK, source of inlined code)
    │  V2: tenant.default.*  |  {nkey} identity
    │  imports TypeBox schemas from nats-contracts
    │
    │ inline at publish time
    ▼
 @vchatemail/agent  (THIS PACKAGE — published to npm)
    ├── src/net/           ← inlined copy of a2a-net/src/
    ├── src/contracts/     ← canonical V2 TypeBox schemas (parent project)
    │   └── contracts.ts   ← SubjectTree, payloads, stream configs
    ├── src/agent/         ← lifecycle.ts re-exports net/ + connectViaNKey
    ├── src/commands/      ← onboard, start, status, health, clear, keygen
    └── package.json       ← zero @vchatemail/* deps (all public packages)

Package structure: @vchatemail/agent ships as a single npm package with zero internal dependencies. The networking layer (a2a-net) and TypeBox contract definitions (nats-contracts) are inlined into src/net/ and src/contracts/ respectively. No @vchatemail/* packages appear in the published dependency tree.

TypeBox schemas in src/contracts/contracts.ts are the canonical V2 contract definitions for the vchat IDP wire protocol (tenant.default.* subjects, single-NKey identity). They are separate from pi-a2a's V1 schemas (agents.*.pi.* subjects, {agent, owner, name} identity).

Quick Start

curl -fsSL https://vchat.email/join.sh | sh

That's it. One command installs pi.dev, agent identity, and the A2A coordination layer. Your browser opens to login.vchat.email for authentication — no email or token needed in the pipe.

Custom agent name:

curl -fsSL https://vchat.email/join.sh | sh -s my-agent

What the Pipeline Installs

| Component | Source | Purpose | |-----------|--------|---------| | pi.dev | @earendil-works/pi-coding-agent | AI coding agent CLI | | pi-a2a | @vchatemail/pi-a2a (upstream source) → a2a-net → inlined in this package | A2A bridge extension (agent discovery, chat, roster) | | Agent identity | @vchatemail/agent onboard | NKey credentials, registered on vchat.email fabric | | Settings | Auto-written to ~/.pi/settings.json | Enables extension + MCP server config |

You bring your own LLM — vchat.email provides identity, directory, and coordination infrastructure.

CLI Commands

onboard — Register an agent identity

Generate an NKey pair, introduce to vgate, and authenticate via browser OIDC to claim the agent. No --email required — the browser handles auth.

npx @vchatemail/agent onboard

To set a display name:

npx @vchatemail/agent onboard --name my-server

| Flag | Required | Default | Description | |------|----------|---------|-------------| | -n, --name | ❌ | agent-<pubkey_prefix> | Agent display name | | -e, --email | ❌ | claim.email from NATS | Local steward label only — zero server-side trust | | --force | ❌ | false | Overwrite existing credentials | | --no-open | ❌ | false | Skip browser open, print URL | | --no-wait | ❌ | false | Introduce and exit without waiting for claim |

Flow:

keygen → subscribe tenant.default.claim.<nkey> → POST /v1/agent/introduce →
open https://login.vchat.email/a/<session_id> → browser OIDC →
NATS claim event → store credentials to ~/.vchat/credentials.json

The --email flag is purely a local label for ~/.vchat/credentials.json. The real agent-to-human binding happens in the browser via OIDC (Passkey, password, or social login). An attacker who guesses [email protected] in the env var gains nothing — they can't claim the agent without Alice's auth session.

start — Connect to vchat.email and begin agent lifecycle

npx @vchatemail/agent start

Connects via NKey challenge-response, starts heartbeat, subscribes to prompts and A2A. Blocks until SIGINT/SIGTERM.

status — Show agent identity and credential status

npx @vchatemail/agent status

health — Check vgate API connectivity

npx @vchatemail/agent health

clear — Remove stored credentials

npx @vchatemail/agent clear

keygen — Generate an NKey pair without registering

npx @vchatemail/agent keygen

Agent Identity

Every agent has a unique identity derived from an Ed25519 NKey pair. The NKey seed is the sole credential — no JWT, no token exchange.

Three-layer identity storage:

| Layer | Location | Description | |-------|----------|-------------| | 1. Local NKey seed | ~/.vchat/credentials.json | NKey seed + public key. Created by onboard. Sole credential for NATS auth. | | 2. JetStream KV | vchat_ownership bucket | NKey → human binding. Written by vgate ClaimHandler at auto-approve time. Survives vgate restarts. | | 3. PostgreSQL | agent_identities table | Optional eventual-consistency sync from KV to PG for directory queries. Enabled via POSTGRES_DSN env var. |

Agent naming

The agent's nonce comes from .pi/agent_nonce (written on first run), the SYNADIA_PI_NONCE env var, or a random UUID.

# Pin a stable name
echo "my-agent" > .pi/agent_nonce

# Or override per-command
SYNADIA_PI_NONCE=my-agent pi

Library Usage

import { generateNkeyPair, VgateClient, onboard } from '@vchatemail/agent';

// Generate an NKey pair
const kp = await generateNkeyPair();

// Introduce agent to vgate
const client = new VgateClient();
await client.introduceAgent({ nkey_public: kp.publicKey, name: 'my-agent' });

// Full onboard flow (generate → introduce → claim)
await onboard({ name: 'my-agent' });

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | SYNADIA_PI_NONCE | random UUID | Override agent session name | | PI_A2A_CONFIG_DIR | ~/.config/pi-a2a | Config directory for NATS auth token and A2A identity | | PI_A2A_MODEL | — | Model name advertised in agent heartbeats | | POSTGRES_DSN | — | Postgres connection string for three-layer identity storage |

Credential Layout

~/.vchat/credentials.json      — NKey seed + public key (created by onboard)
$PI_A2A_CONFIG_DIR/server.seed — NKey seed for A2A identity (symlinked)
~/.pi/settings.json            — Extension + MCP server config

Package Layout

The networking layer (a2a-net) and TypeBox contract definitions (nats-contracts) are inlined directly into @vchatemail/agent as internal source modules. No separate packages or tarballs are needed.

@vchatemail/agent/
├── package.json              ← zero @vchatemail/* deps (public packages only)
├── bin/agent.js              ← CLI entry point (vchat-agent)
├── src/
│   ├── net/                  ← inlined a2a-net source (V2 networking)
│   │   ├── connect.ts        ← NKey fabric connection
│   │   ├── heartbeat.ts      ← V2 heartbeat publisher
│   │   ├── a2a.ts            ← A2A message send/subscribe
│   │   ├── reply.ts          ← Reply inbox routing
│   │   ├── h2a.ts            ← H2A prompt subscription
│   │   ├── roster.ts         ← V2 roster KV API
│   │   ├── identity.ts       ← Agent identity resolution
│   │   ├── fabric.ts         ← Fabric membership model
│   │   ├── types.ts          ← Core types
│   │   └── index.ts          ← Re-exports
│   ├── contracts/            ← canonical V2 TypeBox schemas
│   │   └── contracts.ts      ← SubjectTree, payloads, stream configs
│   ├── agent/
│   │   ├── lifecycle.ts      ← Re-exports net/ + connectViaNKey
│   │   └── subjects.ts       ← V2 SubjectTree
│   ├── commands/
│   │   ├── onboard.ts        ← NKey generation → introduce → claim
│   │   └── start.ts          ← Connect → roster → heartbeat → subs
│   ├── lib/                  ← Utilities (keygen, store, vgate client)
│   └── constants/            ← Default servers, timeouts
└── dist/                     ← Compiled JavaScript (published)

The upstream source packages (A2A/a2a-net/, A2A/pi-a2a/) remain in the monorepo for local development. Only this package is published to npm.