npm package: @godman-protocols/lax
Description: Linked Agent eXchange — agent capability discovery protocol
Author: skingem1
Latest version: 0.3.0

# LAX — Linked Agent eXchange

[![npm version](https://img.shields.io/npm/v/@godman-protocols/lax.svg)](https://www.npmjs.com/package/@godman-protocols/lax)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node: >=20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)

> **v0.3.0** · Apache 2.0 · `@godman-protocols/lax` · Node 20+ / Deno 1.40+

**"Discoverable by design. An agent that cannot be found cannot transact."**

LAX is an open protocol for agent capability discovery. Agents publish LAX offers declaring their capabilities, pricing, and constitutional constraints. Other agents find them via DNS (self-hosted), the LAX Registry, or ClaWHub.

```bash
npm install @godman-protocols/lax
```

---

## The Problem

Multi-agent systems are emerging everywhere, but there is no standard way for agents to advertise what they can do or for other agents to find them. Without a discovery layer, agents are:

- **Invisible** — capabilities exist but no one knows about them
- **Manually wired** — every integration requires bespoke configuration
- **Unverifiable** — no way to check constitutional compliance or trust scores before transacting

LAX is the missing discovery layer between agent capability and agent commerce.

---

## Core Concepts

| Concept | What it is |
|---------|-----------|
| **LaxOffer** | A JSON document at `/.well-known/lax-offer.json` declaring an agent's capabilities, identity, pricing, and constitutional constraints |
| **LaxCapability** | A single skill the agent offers, with input/output schemas and pricing |
| **LaxPricing** | Payment model, amount, currency, and rail for a capability |
| **RegistryClient** | Client for the LAX Registry — register, search, and validate offers |
| **A2AExporter** | Converts LAX offers to Google A2A `/.well-known/agent.json` format |

---

## Three Discovery Mechanisms

1. **Self-hosted**: Serve `/.well-known/lax-offer.json` from your agent's domain
2. **LAX Registry**: `lax.kognai.ai/registry` — search, browse, and validate offers
3. **ClaWHub / OpenClaw**: Auto-published as an OpenClaw skill

Registry access: **Read = free. Write = x402-gated ($0.01 USDC).**

---

## Quick Start

```typescript
import {
  createOffer,
  createCapability,
  validateOffer,
  RegistryClient,
  A2AExporter,
  LAX_VERSION,
} from '@godman-protocols/lax';
import type { LaxOffer } from '@godman-protocols/lax';

// 1. Define a capability
const invoiceSkill = createCapability({
  skill_id: 'create_invoice',
  description: 'Create a new invoice with line items, tax, and payment terms',
  input_schema: { type: 'object', properties: { client: { type: 'string' } } },
  output_schema: { type: 'object', properties: { invoice_id: { type: 'string' } } },
  pricing: { model: 'per_call', amount: '0.01', currency: 'USDC', rail: 'x402' },
});

// 2. Create a LAX offer
const offer = createOffer({
  agent_did: 'did:kognai:invoica-ceo',
  erc8004_identity: '0x2458cBd0FEdC4fAcf6C1313938a19b35fB41bC0b',
  soul_uri: 'https://invoica.kognai.ai/.well-known/soul.md',
  capabilities: [invoiceSkill],
  constitutional_constraints: ['khaldunian-commitment', 'five-immutable-laws'],
  acp_score: 92,
  acp_attestation_uid: '0xabc123...',
  pact_endpoint: 'https://invoica.kognai.ai/pact',
  payment_rails: ['x402', 'usdc-base'],
});

// 3. Validate locally
const result = validateOffer(offer);
console.log(result.valid); // true

// 4. Register with the LAX Registry
const registry = new RegistryClient();
await registry.register(offer);

// 5. Export to A2A format (/.well-known/agent.json)
const a2aCard = A2AExporter.export(
  offer,
  'Invoica CEO',
  'https://invoica.kognai.ai',
  { organization: 'Kognai' }
);
const json = A2AExporter.serialize(a2aCard);
// Write `json` to /.well-known/agent.json
```

---

## Types Reference

### Core Types (`src/types.ts`)

| Type | Description |
|------|-------------|
| `LaxOffer` | The discoverable document an agent publishes |
| `LaxCapability` | A single skill with input/output schemas and pricing |
| `LaxPricing` | Payment model, amount, currency, and rail |
| `RegistrySearchParams` | Search filters for the LAX Registry |
| `RegistrySearchResult` | A search result with offer and relevance score |
| `OfferValidationResult` | Validation result with errors and warnings |
| `A2AAgentCard` | Google A2A agent.json format |
| `A2ASkill` | A2A skill representation |

### Functions & Classes (`src/core.ts`)

| Export | Description |
|--------|-------------|
| `createOffer(params)` | Create a LaxOffer with defaults |
| `createCapability(params)` | Create a LaxCapability entry |
| `validateOffer(offer)` | Local structural validation of an offer |
| `RegistryClient` | Registry client — `register()`, `search()`, `validate()` |
| `A2AExporter` | Export to A2A format — `export()`, `serialize()` |
| `fetchOffer(baseUrl)` | Fetch a LAX offer from `/.well-known/lax-offer.json` |
| `fetchA2ACard(baseUrl)` | Fetch an A2A card from `/.well-known/agent.json` |

---

## Open vs Proprietary

| Open-Source (Apache 2.0) | Proprietary |
|--------------------------|-------------|
| Offer schema | Registry infrastructure |
| Discovery mechanism | Ranking algorithm |
| A2A export | Enterprise private registries |
| SDK (this package) | |

---

## Composability with Other Protocols

| Protocol | How LAX connects |
|----------|------------------|
| **PACT** | LAX offer declares `pact_endpoint` — agents discover via LAX, then negotiate via PACT |
| **SOUL** | LAX offer includes `soul_uri` — constitutional identity verified before transaction |
| **SCORE** | `acp_score` in LAX offer comes from SCORE's constitutional output rating |
| **AMF** | Memory vectors from AMF inform capability descriptions and pricing adjustments |
| **DRS** | Deal receipts reference the LAX `skill_id` used in the transaction |
| **SIGNAL** | Reward signals feed back into `acp_score` updates in LAX offers |

---

## License

Apache License 2.0 — see [LICENSE](./LICENSE)

Part of the [Godman Protocols](https://github.com/godman-protocols) portfolio.