@kadi.build/core 0.0.1-alpha.3 → 0.0.1-alpha.5

package/README.md

@@ -7,7 +7,7 @@
 
 ## 🎯 Overview
 
-`@kadi.build/core` is the foundational library for creating KADI abilities - modular, protocol-agnostic services that can communicate via multiple transport layers. Whether you're building local tools, distributed microservices, or high-performance native modules, this toolkit provides a unified, developer-friendly API that abstracts away transport complexity.
+`@kadi.build/core` is the foundational library for creating KADI abilities - modular, protocol-agnostic components that can communicate via multiple transport layers. Whether you're building local tools, distributed systems, or high-performance native modules, this toolkit provides a unified, developer-friendly API that abstracts away transport complexity.
 
 ## 📚 Table of Contents
 
@@ -16,6 +16,7 @@
 - [🚀 Quick Start](#-quick-start)
 - [🔌 Transport Protocols](#-transport-protocols)
 - [🛠️ Creating Abilities](#-creating-abilities)
+- [🤖 Creating Agents](#-creating-agents)
 - [🔄 Architecture Deep Dive](#-architecture-deep-dive)
 - [📥 Loading Abilities](#-loading-abilities)
 - [⚙️ Configuration](#-configuration)
@@ -44,21 +45,26 @@ npm install -g @kadi.build/cli
 
 ## 🚀 Quick Start
 
+The library provides a unified way to work with KADI through the **KadiClient** class, which can operate in multiple roles:
+
+- **As an Ability**: Serving tools/methods that others can call
+- **As an Agent**: Calling remote tools via broker protocol
+
 ### Creating Your First Ability
 
 ```javascript
 #!/usr/bin/env node
-import { KadiAbility } from '@kadi.build/core';
+import { KadiClient } from '@kadi.build/core';
 
-// Create an ability instance
-const mathAbility = new KadiAbility({
+// Create a ability instance
+const mathAbility = new KadiClient({
   name: 'math-ability',
-  version: '1.0.0',
-  description: 'Simple math operations'
+  role: 'ability', // 'agent', 'ability'
+  protocol: 'stdio' // 'native', 'stdio', or 'broker'
 });
 
-// Register a method
-mathAbility.method('add', async ({ a, b }) => {
+// Register a tool
+mathAbility.registerTool('add', async ({ a, b }) => {
   return { result: a + b };
 });
 
@@ -78,14 +84,58 @@ async function main() {
   // Call methods like regular functions
   const result = await math.add({ a: 5, b: 3 });
   console.log(result); // { result: 8 }
-
-  // List available methods
-  console.log(math.__list()); // ['add']
 }
 
 main().catch(console.error);
 ```
 
+### Creating a Broker-Connected Agent
+
+```javascript
+import { KadiClient } from '@kadi.build/core';
+
+// Create an agent that connects to broker
+const agent = new KadiClient({
+  name: 'my-agent',
+  role: 'agent',
+  protocol: 'broker',
+  brokers: {
+    'prod': 'ws://localhost:8080',
+    'dev': 'ws://localhost:8081'
+  },
+  defaultBroker: 'prod',
+  networks: ['global']
+});
+
+// Register tools that other agents can call
+agent.registerTool(
+  'greet',
+  async ({ name }) => {
+    return { greeting: `Hello, ${name}!` };
+  },
+  {
+    description: 'Greet someone by name',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name to greet' }
+      },
+      required: ['name']
+    }
+  }
+);
+
+// Connect to brokers and start serving
+await agent.connectToBrokers();
+
+// Call tools from OTHER agents connected to the same broker
+const result = await agent.callTool('translate', 'text-tool', {
+  text: 'Hello world',
+  language: 'spanish'
+});
+console.log(result);
+```
+
 ## 🔌 Transport Protocols
 
 KADI abilities support three transport protocols, each optimized for different use cases:
@@ -107,7 +157,7 @@ const ability = await loadAbility('my-ability', 'native');
 - **Use Case**: Language-agnostic local execution
 - **How it Works**: Spawns abilities as child processes, communicates via LSP-style JSON-RPC over stdin/stdout
 - **Performance**: Minimal overhead, reliable local IPC
-- **Best For**: Python scripts, Go binaries, Node.js services, development/testing
+- **Best For**: Python scripts, Go binaries, Node.js abilities, development/testing
 
 ```javascript
 // Force stdio protocol
@@ -123,10 +173,10 @@ KADI_PROTOCOL=stdio  # Identifies the protocol being used
 
 ### 3. Broker Protocol (Distributed)
 
-- **Use Case**: Distributed services, containerized deployments
+- **Use Case**: Distributed systems, containerized deployments
 - **How it Works**: Abilities connect to a WebSocket broker for network communication
 - **Performance**: Network overhead, but enables scaling and distribution
-- **Best For**: Microservices, cloud deployments, load-balanced services
+- **Best For**: Distributed abilities, cloud deployments, load-balanced systems
 
 ```javascript
 // Use broker for distributed execution
@@ -136,77 +186,67 @@ const ability = await loadAbility('my-ability', 'broker');
 **Environment Variables Passed to Child Process:**
 
 ```bash
-KADI_PROTOCOL=broker                        # Identifies the protocol
+KADI_PROTOCOL=broker                       # Identifies the protocol
 KADI_BROKER_URL=ws://localhost:8080        # Broker connection URL
-KADI_SERVICE_NAME=ability.echo.1_0_0       # Service identifier
+KADI_ABILITY_NAME=ability.echo.1_0_0       # Ability identifier
 KADI_AGENT_SCOPE=uuid-here                 # Agent's scope/namespace
 # Plus all parent process.env variables
 ```
 
-**Scope/Namespace Visibility:**
+**Network/Namespace Visibility:**
 
-The `KADI_AGENT_SCOPE` environment variable represents the agent's namespace. For the ability to be visible to its parent agent via the broker, it must register with the same scope:
+The `KADI_AGENT_SCOPE` environment variable represents the agent's namespace. For the ability to be visible to its parent agent via the broker, it must register with the same network:
 
 ```javascript
 // In your ability code:
-const echoAbility = new KadiAbility({
+const echoAbility = new KadiClient({
   name: 'echo-js',
   version: '0.0.1',
   description: 'Echo ability with broker support',
-  scope: process.env.KADI_AGENT_SCOPE // Use agent's scope for visibility
+  network: process.env.KADI_AGENT_SCOPE // Use agent's network for visibility
 });
 
-// Without this, the ability would only be visible in the 'global' scope
+// Without this, the ability would only be visible in the 'global' network
 // and the parent agent wouldn't be able to communicate with it
 ```
 
 ### Protocol Selection Strategy
 
-When no protocol is specified, `loadAbility` uses the **first interface** defined in the ability's `agent.json`. The KADI team recommends ordering interfaces from fastest to slowest (native → stdio → broker) for optimal default performance.
+When no protocol is specified, `loadAbility` defaults to the 'native' protocol. You must explicitly specify the protocol if you want to use 'stdio' or 'broker'.
 
 ```mermaid
 graph TD
     A[Load Ability] --> B{Protocol Specified?}
     B -->|Yes| C[Use Specified Protocol]
-    B -->|No| D{Check agent.json interfaces}
-    D --> E[Use First Interface Listed]
-    E --> F[native/stdio/broker]
-```
-
-**Recommended Interface Order in agent.json:**
-
-```json
-{
-  "interfaces": {
-    "native": { "entry": "service.js" }, // 1st choice: Fastest
-    "stdio": { "discover": true }, // 2nd choice: Balanced
-    "broker": { "discover": true } // 3rd choice: Distributed
-  }
-}
+    B -->|No| D[Default to 'native']
 ```
 
-## 🛠️ Creating Abilities
+## 🛠️ Creating Abilities with KadiClient
 
 ### Basic Ability Structure
 
 ```javascript
-import { KadiAbility } from '@kadi.build/core';
+import { KadiClient } from '@kadi.build/core';
 
-const ability = new KadiAbility({
+const ability = new KadiClient({
   name: 'echo-ability',
-  version: '1.0.0',
-  description: 'Echo service with metadata',
-  scope: process.env.KADI_AGENT_SCOPE || 'global'
+  role: 'ability', // 'agent', 'ability',
+  protocol: 'stdio', // 'native', 'stdio', or 'broker'
+  brokers: {
+    'local': 'ws://localhost:8080',
+    'prod': 'ws://api.example.com:8080'
+  },
+  defaultBroker: 'local'
 });
 
-// Method 1: Simple handler
-ability.method('echo', async ({ message }) => ({
+// Method 1: Simple tool registration
+ability.registerTool('echo', async ({ message }) => ({
   echo: message,
   timestamp: new Date().toISOString()
 }));
 
-// Method 2: Handler with inline schema
-ability.method(
+// Method 2: Tool with inline schema
+ability.registerTool(
   'format',
   async ({ text, style }) => ({
     formatted: style === 'upper' ? text.toUpperCase() : text.toLowerCase()
@@ -240,40 +280,60 @@ ability.serve().catch(console.error);
 
 ### Event Publishing and Subscription
 
-**Note**: Events currently work for `native` and `stdio` protocols. Broker protocol event support is planned for future releases.
+**Full Support**: Events work across all protocols - native, stdio, and broker.
 
-Abilities can publish events that agents can subscribe to:
+KadiClient provides a unified event system that works consistently across all transport protocols:
 
 ```javascript
-// In your ability (service.js)
-const ability = new KadiAbility({ name: 'my-ability' });
+// In your ability (ability.js)
+const ability = new KadiClient({
+  name: 'my-ability',
+  role: 'ability',
+  protocol: 'broker' // Works with all protocols
+});
 
-// Publish events from method handlers
-ability.method('echo', async ({ message }) => {
-  // Publish an event before returning the result
-  ability.publishEvent('echo:test-event', { from: 'message echo' });
-  ability.publishEvent('echo:test-event', { from: 'message echo 2' });
+// Publish events from tool handlers
+ability.registerTool('echo', async ({ message }) => {
+  // Publish events during processing
+  await ability.publishEvent('echo.processing', { status: 'started' });
+
+  // Do work...
+  const result = { echo: message, timestamp: new Date().toISOString() };
 
-  return { echo: message, timestamp: new Date().toISOString() };
+  await ability.publishEvent('echo.completed', { result });
+  return result;
 });
 
-// In your agent (index.js)
-const ability = await loadAbility('my-ability');
+// In your agent (agent.js)
+const agent = new KadiClient({
+  name: 'my-client',
+  role: 'agent',
+  protocol: 'broker'
+});
 
-// Subscribe to events BEFORE calling methods that emit them
-ability.events.on('echo:test-event', (data) => {
-  console.log(`[NATIVE] echo:test-event received:`, data);
+// Subscribe to events using patterns
+agent.subscribeToEvent('echo.*', (data) => {
+  console.log('Echo event received:', data);
 });
 
-// Now call the method that emits events
-const result = await ability.echo({ message: 'Hello world' });
+// For loaded abilities with native/stdio protocols
+const ability = await loadAbility('my-ability', 'stdio');
+ability.events.on('echo.completed', (data) => {
+  console.log('Completed:', data);
+});
 ```
 
-**Important**: Always subscribe to events before calling methods that emit them, as events are emitted immediately when `publishEvent()` is called.
+**Event Patterns**:
+
+- Use wildcards: `math.*` matches `math.operation`, `math.milestone`
+- Protocol-specific delivery:
+  - **Native**: Direct EventEmitter (synchronous)
+  - **Stdio**: JSON-RPC notifications over stdout
+  - **Broker**: RabbitMQ pub/sub via WebSocket
 
 ### Ability Configuration (agent.json)
 
-Every ability should have an `agent.json` file that defines its capabilities and interfaces:
+Every ability should have an `agent.json` file that defines its capabilities:
 
 ```json
 {
@@ -281,24 +341,10 @@ Every ability should have an `agent.json` file that defines its capabilities and
   "kind": "ability",
   "version": "1.0.0",
   "license": "MIT",
-  "description": "Echo service with multiple transport support",
+  "description": "Echo ability with multiple transport support",
   "scripts": {
     "setup": "npm install",
-    "start": "node service.js"
-  },
-  "interfaces": {
-    "native": {
-      "entry": "service.js"
-    },
-    "stdio": {
-      "discover": true,
-      "timeoutMs": 10000
-    },
-    "broker": {
-      "discover": true,
-      "timeoutMs": 15000,
-      "serviceName": "echo-service"
-    }
+    "start": "node ability.js"
   },
   "exports": [
     {
@@ -323,7 +369,8 @@ Every ability should have an `agent.json` file that defines its capabilities and
   "brokers": {
     "local": "ws://localhost:8080",
     "remote": "ws://api.example.com:8080"
-  }
+  },
+  "defaultBroker": "local"
 }
 ```
 
@@ -332,7 +379,7 @@ Every ability should have an `agent.json` file that defines its capabilities and
 The ability system provides two ways to define method schemas:
 
 1. **Export Schemas** (defined in `agent.json` exports section)
-2. **Inline Schemas** (passed directly to `.method()`)
+2. **Inline Schemas** (passed directly to `registerTool()`)
 
 ```javascript
 // Option 1: Define in agent.json exports section
@@ -350,7 +397,7 @@ The ability system provides two ways to define method schemas:
 }
 
 // Option 2: Define inline when registering the method
-ability.method('process', handler, {
+ability.registerTool('process', handler, {
   description: 'Process data',
   inputSchema: { /* ... */ },
   outputSchema: { /* ... */ }
@@ -361,176 +408,327 @@ ability.method('process', handler, {
 
 **Important**: Specifying MCP schemas for ability handlers is particularly important for `broker` communication. If you only need `native` and `stdio` protocols, schemas can be omitted.
 
+## 🤖 Working with KadiClient
+
+KadiClient is the unified API for all KADI operations. It replaces the previous separate KadiAbility and KadiAgent classes with a single, powerful interface that can operate in multiple roles.
+
+### Direct Approach (using loadAbility)
+
+```javascript
+import { loadAbility } from '@kadi.build/core';
+
+// Load and call abilities directly
+const echoAbility = await loadAbility('echo-js', 'stdio');
+const result = await echoAbility.echo({ message: 'Hello world' });
+
+// Load broker tools directly
+const remoteAbility = await loadAbility('remote-ability', 'broker', {
+  brokerUrl: 'ws://localhost:8080',
+  networks: ['global']
+});
+const brokerResult = await remoteAbility.process({ data: 'test' });
+```
+
+### Using KadiClient with Named Brokers
+
+```javascript
+import { KadiClient } from '@kadi.build/core';
+
+// Create a unified client with named brokers
+const client = new KadiClient({
+  name: 'my-ability',
+  role: 'ability', // Provider role
+  protocol: 'broker',
+  brokers: {
+    'dev': 'ws://localhost:8080',
+    'staging': 'ws://staging.example.com:8080',
+    'prod': 'ws://prod.example.com:8080'
+  },
+  defaultBroker: 'dev',
+  networks: ['global']
+});
+
+// Register tools for others to call
+client.registerTool(
+  'greet',
+  async ({ name }) => {
+    return { greeting: `Hello, ${name}!` };
+  },
+  {
+    description: 'Greet someone by name',
+    inputSchema: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name']
+    }
+  }
+);
+
+// Connect to all configured brokers
+await client.connectToBrokers();
+
+// Call remote tools
+const result = await client.callTool('translator', 'translate', {
+  text: 'Hello',
+  to: 'es'
+});
+
+// Load abilities for compatibility
+const ability = await client.loadAbility('echo-js');
+```
+
+Use `loadAbility()` for simple consumption, or KadiClient for full-featured ability development with tool registration, event publishing, and remote tool invocation.
+
 ## 🔄 Architecture Deep Dive
 
-### Ability Loading Sequence
+### Transport Architecture and Loading Sequence
 
-The loading process adapts based on the selected protocol:
+The loading process uses modular transports based on the selected protocol:
 
 ```mermaid
 sequenceDiagram
     participant Client
     participant loadAbility
+    participant Transport
     participant FileSystem
     participant ChildProcess
     participant Ability
     participant Broker
 
     Client->>loadAbility: loadAbility('echo-js', protocol?)
-    loadAbility->>FileSystem: Read project/ability agent.json
-    FileSystem-->>loadAbility: Return ability version & config
-    loadAbility->>FileSystem: Check ability directory exists
-    loadAbility->>FileSystem: Read ability's agent.json manifest
+    loadAbility->>FileSystem: Read agent.json manifests
+    FileSystem-->>loadAbility: Return config & version
 
     alt protocol === 'native'
-        loadAbility->>FileSystem: Read entry point from manifest
-        loadAbility->>Ability: import(modulePath)
-        Ability-->>loadAbility: Return module exports
-        loadAbility->>loadAbility: Extract functions from module
-        loadAbility->>loadAbility: Build proxy with direct function calls
+        loadAbility->>Transport: new NativeTransport(config)
+        Transport->>FileSystem: import(entry point)
+        FileSystem-->>Transport: Module with KadiClient instance
+        Transport->>Ability: Extract tool handlers via getToolNames()
+        Ability-->>Transport: Return registered tools
+        Transport->>Transport: Store handlers in Map
     else protocol === 'stdio'
-        loadAbility->>ChildProcess: spawn(startCmd, { env: { KADI_PROTOCOL: 'stdio' }})
-        ChildProcess->>Ability: Start ability process
-        Ability->>Ability: Create StdioRpcServer
-        loadAbility->>Ability: Send __kadi_init via LSP frames
-        Ability-->>loadAbility: Return { name, version, functions }
-
-        opt if discover enabled
-            loadAbility->>Ability: Send __kadi_discover
-            Ability-->>loadAbility: Return { functions: {...} }
-        end
-
-        loadAbility->>loadAbility: Merge static exports + discovered functions
-        loadAbility->>loadAbility: Build proxy with RPC calls
+        loadAbility->>Transport: new StdioTransport(config)
+        Transport->>ChildProcess: spawn(startCmd, env: {KADI_PROTOCOL})
+        ChildProcess->>Ability: KadiClient detects stdio mode
+        Ability->>Ability: Setup FrameReader/Writer
+        Transport->>Ability: Send discovery request
+        Ability-->>Transport: Return tool list
+        Transport->>Transport: Setup JSON-RPC proxy
     else protocol === 'broker'
-        loadAbility->>loadAbility: Generate scope UUID
-        loadAbility->>ChildProcess: spawn(startCmd, { env: { KADI_PROTOCOL, KADI_BROKER_URL, KADI_AGENT_SCOPE, KADI_SERVICE_NAME }})
-        ChildProcess->>Ability: Start ability process
-
-        Note over Ability,Broker: Ability connects to broker
-        Ability->>Broker: WebSocket connect
-        Ability->>Broker: hello({ role: 'agent' })
-        Broker-->>Ability: { nonce }
-        Ability->>Broker: authenticate({ publicKey, signature })
-        Broker-->>Ability: { agentId }
-        Ability->>Broker: registerCapabilities({ tools, scopes: [KADI_AGENT_SCOPE] })
-
-        Note over loadAbility,Broker: Parent connects to broker
-        loadAbility->>Broker: WebSocket connect
-        loadAbility->>Broker: hello/auth/register sequence
-
-        opt if discover enabled
-            loadAbility->>Broker: listTools({ scopes: [scope] })
-            Broker-->>loadAbility: Return available tools
-        end
-
-        loadAbility->>loadAbility: Merge static exports + broker tools
-        loadAbility->>loadAbility: Build proxy with broker RPC
+        loadAbility->>Transport: new BrokerTransport(config)
+        Transport->>Transport: Reuse existing KadiClient
+        Transport->>Broker: WebSocket connect
+        Transport->>Broker: kadi.session.hello
+        Broker-->>Transport: { nonce, heartbeatIntervalSec }
+        Transport->>Broker: kadi.session.authenticate
+        Broker-->>Transport: { sessionId }
+        Transport->>Broker: kadi.ability.list
+        Broker-->>Transport: Available tools
+        Transport->>Transport: Start heartbeat timer
     end
 
-    loadAbility->>Client: Return ability proxy
-    Client->>Client: ability.method({ params })
+    loadAbility->>loadAbility: Create proxy with tool methods
+    loadAbility-->>Client: Return ability proxy
+
+    Note over Client,Ability: Tool invocation
+    Client->>Transport: ability.echo({ message })
+
+    alt native
+        Transport->>Ability: Direct handler call
+    else stdio
+        Transport->>Ability: JSON-RPC over frames
+    else broker
+        Transport->>Broker: kadi.ability.invoke
+        Broker->>Ability: Route to target
+        Ability->>Broker: kadi.ability.result
+        Broker-->>Transport: Forward result
+    end
+
+    Transport-->>Client: Return result
 ```
 
-### Method Registration & Serving
+### KadiClient Architecture: Tool Registration & Serving
 
-How abilities register methods and start serving:
+How KadiClient registers tools and starts serving:
 
 ```mermaid
 sequenceDiagram
     participant Dev as Developer
-    participant KA as KadiAbility
-    participant Server as RpcServer
+    participant KC as KadiClient
     participant Transport
-    participant Client
+    participant Network as Network Layer
+    participant RemoteClient
 
-    Note over Dev,KA: Registration Phase
-    Dev->>KA: new KadiAbility({ name, scope: process.env.KADI_AGENT_SCOPE })
-    Dev->>KA: ability.method('echo', handler)
-    KA->>KA: Store in methodHandlers Map
+    Note over Dev,KC: Tool Registration Phase
+    Dev->>KC: new KadiClient({ name, role, protocol })
+    KC->>KC: Initialize based on role & protocol
 
-    Dev->>KA: ability.method('transform', handler, schema)
-    KA->>KA: Store handler in methodHandlers
-    KA->>KA: Store schema in methodMCPSchemas
+    Dev->>KC: registerTool('echo', handler, schema?)
+    KC->>KC: Store in toolHandlers Map<name, {handler, schema}>
 
-    Note over KA,Transport: Serving Phase
-    Dev->>KA: ability.serve()
-    KA->>KA: Detect protocol from env/options
+    Dev->>KC: registerTool('process', handler, schema)
+    KC->>KC: Add to toolHandlers Map
 
-    alt protocol === 'stdio'
-        KA->>Server: new StdioRpcServer()
-        Server->>Transport: new StdioFrameReader(stdin)
-        Server->>Transport: new StdioFrameWriter(stdout)
-        Transport->>Transport: Listen for LSP frames on stdin
+    Note over KC,Network: Connection & Serving Phase
+    Dev->>KC: serve() or connectToBrokers()
+
+    alt protocol === 'native'
+        KC->>KC: Tools available via direct reference
+        KC->>KC: Emit 'start' event
+    else protocol === 'stdio'
+        KC->>Transport: Setup StdioTransport
+        Transport->>Transport: new FrameReader(stdin)
+        Transport->>Transport: new FrameWriter(stdout)
+        Transport->>KC: on('message', handleStdioMessage)
+        KC->>KC: Process JSON-RPC requests
     else protocol === 'broker'
-        KA->>Server: new BrokerRpcServer()
-        Server->>Transport: WebSocket connect to broker
-        Server->>Transport: Handshake (hello/auth)
-        Server->>KA: ability.extractToolsForBroker()
-        KA-->>Server: Return tools from exports + inline schemas
-        Server->>Transport: registerCapabilities({ tools, scopes })
+        KC->>Network: WebSocket.connect(brokerUrl)
+        KC->>Network: kadi.session.hello({ role })
+        Network-->>KC: { nonce, heartbeatIntervalSec: 30 }
+        KC->>KC: Sign nonce with Ed25519
+        KC->>Network: kadi.session.authenticate({ signature })
+        Network-->>KC: { sessionId }
+        KC->>Network: kadi.agent.register({ tools, networks })
+        KC->>KC: Start heartbeat timer (30s interval)
     end
 
-    Server->>KA: Forward events (start, request, response, error)
+    Note over RemoteClient,KC: Tool Invocation Flow
+    RemoteClient->>Network: Request tool invocation
+
+    alt native
+        RemoteClient->>KC: Direct method call
+        KC->>KC: toolHandlers.get(name).handler(params)
+    else stdio
+        Network->>Transport: JSON-RPC frame
+        Transport->>KC: Parsed request
+        KC->>KC: toolHandlers.get(name).handler(params)
+        KC->>Transport: JSON-RPC response
+        Transport->>Network: Framed response
+    else broker
+        Network->>KC: kadi.ability.invoke message
+        KC->>KC: toolHandlers.get(toolName).handler(params)
+        KC->>Network: kadi.ability.result message
+    end
 
-    Note over Transport,Client: Request Handling
-    Client->>Transport: Incoming request
-    Transport->>Server: Parse & validate request
-    Server->>KA: getMethodHandler(method)
-    KA-->>Server: Return handler function
-    Server->>Server: Execute handler with timeout
-    Server->>Transport: Send response
-    Transport->>Client: Return result
+    Network-->>RemoteClient: Tool result
+```
+
+### Event System Architecture
+
+KadiClient provides a unified event API that works across all transport protocols:
+
+```mermaid
+sequenceDiagram
+    participant Publisher as Ability (Publisher)
+    participant Transport as Transport Layer
+    participant EventBus as Event Bus
+    participant Subscriber as Client (Subscriber)
+
+    Note over Subscriber: Setup subscription
+    Subscriber->>Subscriber: subscribeToEvent('math.*', callback)
+
+    alt protocol === 'broker'
+        Subscriber->>EventBus: kadi.event.subscribe({channels: ['math.*']})
+        EventBus-->>Subscriber: {subscribed: ['math.*'], queueName}
+    else protocol === 'stdio'
+        Subscriber->>Transport: Setup event listener
+        Transport->>Subscriber: on('transport:event', dispatcher)
+    else protocol === 'native'
+        Subscriber->>Publisher: Direct EventEmitter reference
+        Publisher->>Subscriber: on('ability:event', dispatcher)
+    end
+
+    Note over Publisher: Publish event
+    Publisher->>Publisher: publishEvent('math.operation', data)
+
+    alt protocol === 'native'
+        Publisher->>Publisher: emit('ability:event', {eventName, data})
+        Publisher-->>Subscriber: Direct EventEmitter delivery
+        Subscriber->>Subscriber: Pattern match & invoke callback
+    else protocol === 'stdio'
+        Publisher->>Transport: writer.write(__kadi_event notification)
+        Transport->>Transport: Frame with LSP headers
+        Transport-->>Subscriber: Framed event over stdout
+        Subscriber->>Transport: FrameReader parses
+        Transport->>Subscriber: emit('transport:event', {name, data})
+        Subscriber->>Subscriber: Pattern match & invoke callback
+    else protocol === 'broker'
+        Publisher->>EventBus: kadi.event.publish({channel, data})
+        EventBus->>EventBus: Route via RabbitMQ
+        EventBus-->>Subscriber: kadi.event.delivery
+        Subscriber->>Subscriber: Pattern match & invoke callback
+    end
+
+    Note over Subscriber: Cleanup
+    Subscriber->>Subscriber: unsubscribe()
+    alt protocol === 'broker'
+        Subscriber->>EventBus: kadi.event.unsubscribe
+    else
+        Subscriber->>Subscriber: Remove local listener
+    end
 ```
 
 ### Broker Protocol Communication Flow
 
-Detailed view of broker-based communication:
+Detailed view of broker-based communication with heartbeat:
 
 ```mermaid
 sequenceDiagram
-    participant Agent as Agent (Parent)
-    participant Ability as Ability (Child)
+    participant Client as KadiClient
     participant Broker as KADI Broker
-    participant Consumer as Other Agent/Client
-
-    Note over Agent,Ability: Initialization
-    Agent->>Agent: Generate scope UUID
-    Agent->>Ability: spawn(env: { KADI_AGENT_SCOPE: uuid })
-
-    Note over Ability,Broker: Ability Registration
-    Ability->>Broker: Connect WebSocket
-    Ability->>Broker: hello({ role: 'agent' })
-    Broker-->>Ability: { nonce: 'abc123' }
-    Ability->>Ability: Generate ephemeral Ed25519 keypair
-    Ability->>Broker: authenticate({ publicKey, signature(nonce) })
-    Broker-->>Ability: { agentId: 'ability-123' }
-    Ability->>Broker: registerCapabilities({ tools: [...], scopes: [uuid] })
-    Broker->>Broker: Store capabilities in scope
-
-    Note over Agent,Broker: Agent Connection
-    Agent->>Broker: Connect WebSocket
-    Agent->>Broker: hello/authenticate sequence
-    Broker-->>Agent: { agentId: 'agent-456' }
-
-    Note over Agent,Broker: Method Call via Broker
-    Agent->>Broker: callAbility({ toolName: 'echo', args: { message: 'test' }, requestId })
-    Broker-->>Agent: { requestId }
-    Broker->>Ability: agent.message({ toolName, args, requestId, from: 'agent-456' })
-    Ability->>Ability: Execute handler
-    Ability->>Broker: ability.result({ requestId, toSessionId: 'agent-456', result })
-    Broker->>Agent: ability.result({ requestId, result })
-
-    Note over Broker,Consumer: Scope Isolation
-    Consumer->>Broker: listTools({ scopes: ['global'] })
-    Broker-->>Consumer: { tools: [] } // Ability not visible (wrong scope)
-    Consumer->>Broker: listTools({ scopes: [uuid] })
-    Broker-->>Consumer: { tools: ['echo', 'transform'] } // Now visible
+    participant Target as Target Ability
+
+    Note over Client,Broker: Connection & Authentication
+    Client->>Broker: WebSocket connect
+    Client->>Broker: kadi.session.hello({ role })
+    Broker-->>Client: { nonce, heartbeatIntervalSec: 30 }
+    Client->>Client: Generate Ed25519 keypair
+    Client->>Client: Sign nonce
+    Client->>Broker: kadi.session.authenticate({ signature })
+    Broker-->>Client: { sessionId }
+
+    Note over Client,Broker: Heartbeat Management
+    Client->>Client: Start heartbeat timer (30s)
+    loop Every 30 seconds
+        Client->>Broker: kadi.session.ping
+        Note over Broker: Reset connection timeout (90s)
+    end
+
+    Note over Client,Broker: Tool Registration
+    Client->>Broker: kadi.agent.register({ tools, networks })
+    Broker->>Broker: Store in registry
+    Broker-->>Client: { registered: true }
+
+    Note over Client,Target: Remote Tool Invocation
+    Client->>Client: callTool('ability-b', 'process', params)
+    Client->>Broker: kadi.ability.invoke({
+        targetAgent: 'ability-b',
+        toolName: 'process',
+        toolInput: params
+    })
+    Broker->>Broker: Lookup ability-b
+    Broker->>Target: kadi.ability.invoke
+    Target->>Target: Execute tool handler
+    Target->>Broker: JSON-RPC response
+    Broker-->>Client: Forward response
+    Client->>Client: Resolve promise
+
+    Note over Client,Broker: Event Publishing
+    Client->>Broker: kadi.event.publish({
+        channel: 'system.status',
+        data: { status: 'healthy' }
+    })
+    Broker->>Broker: Publish to RabbitMQ exchange
+
+    Note over Client,Broker: Graceful Shutdown
+    Client->>Client: Stop heartbeat timer
+    Client->>Broker: kadi.session.goodbye
+    Client->>Client: Close WebSocket
 ```
 
-### Stdio Protocol Frame Processing
+### Stdio Protocol: LSP-Style Frame Processing
 
-How LSP-style frames are processed:
+How KadiClient handles stdio communication with LSP-style framing:
 
 ```mermaid
 sequenceDiagram
@@ -538,10 +736,10 @@ sequenceDiagram
     participant SR as StdioFrameReader
     participant SW as StdioFrameWriter
     participant Server as StdioRpcServer
-    participant Ability as KadiAbility
+    participant Ability as KadiClient
 
     Note over Parent,SR: Incoming Request
-    Parent->>SR: Write to stdin: "Kadi-Content-Length: 52\r\n\r\n{...}"
+    Parent->>SR: Write to stdin: "Content-Length: 52\r\n\r\n{...}"
     SR->>SR: Buffer incoming data
     SR->>SR: Look for Content-Length header
     SR->>SR: Parse header, extract body length
@@ -558,7 +756,7 @@ sequenceDiagram
     Server->>SW: write(response)
     SW->>SW: JSON.stringify(response)
     SW->>SW: Calculate byte length
-    SW->>SW: Create header: "Kadi-Content-Length: N\r\n\r\n"
+    SW->>SW: Create header: "Content-Length: N\r\n\r\n"
     SW->>Parent: Write header + body to stdout
 
     Note over SR: Error Recovery
@@ -590,22 +788,21 @@ const nativeAbility = await loadAbility('my-ability', 'native');
 ### Working with Loaded Abilities
 
 ```javascript
-// List available methods
-const methods = ability.__list();
-console.log('Available methods:', methods);
+// Call methods directly - no need to discover them first
+const result = await ability.echo({ message: 'hello' });
 
 // Call methods
 const result = await ability.someMethod({ param: 'value' });
 
 // Direct RPC call (bypasses method validation)
-const response = await ability.call('someMethod', { param: 'value' });
+const response = await ability.__call('someMethod', { param: 'value' });
 
 // Subscribe to events
 ability.events.on('custom:event', (data) => {
   console.log('Event received:', data);
 });
 
-// Note: Events work for native and stdio protocols
+// Note: Events work for all protocols (native, stdio, and broker)
 // Subscribe before calling methods that emit events
 ```
 
@@ -627,7 +824,7 @@ export KADI_PROTOCOL=stdio
 
 # Configure broker
 export KADI_BROKER_URL=ws://localhost:8080
-export KADI_SERVICE_NAME=my-service
+export KADI_ABILITY_NAME=my-ability
 export KADI_AGENT_SCOPE=project-123
 ```
 
@@ -638,19 +835,19 @@ When abilities are spawned as child processes (stdio and broker protocols), the
 ```javascript
 // In your ability code, you can access these variables:
 const protocol = process.env.KADI_PROTOCOL; // 'stdio' or 'broker'
-const brokerUrl = process.env.KADI_BROKER_URL; // For broker protocol
-const serviceName = process.env.KADI_SERVICE_NAME; // For broker protocol
-const agentScope = process.env.KADI_AGENT_SCOPE; // For broker protocol
+const brokerUrl = process.env.KADI_BROKER_URL;
+const abilityName = process.env.KADI_ABILITY_NAME;
+const agentScope = process.env.KADI_AGENT_SCOPE;
 
 // Use them to configure your ability behavior
-const ability = new KadiAbility({
+const ability = new KadiClient({
   name: 'my-ability',
-  scope: process.env.KADI_AGENT_SCOPE || 'global'
+  network: process.env.KADI_AGENT_SCOPE || 'global'
   // Ability automatically uses KADI_PROTOCOL to determine transport
 });
 ```
 
-### Project Structure
+### Example Project Structure
 
 ```
 my-project/
@@ -659,7 +856,7 @@ my-project/
 │   └── echo-ability/
 │       └── 1.0.0/
 │           ├── agent.json  # Ability configuration
-│           ├── service.js  # Ability implementation
+│           ├── ability.js  # Ability implementation
 │           └── package.json
 ├── modules/                # Source modules
 │   └── echo-ability/       # Development version
@@ -670,100 +867,159 @@ my-project/
 
 ### Event System
 
-KADI abilities support two types of events:
+KadiClient provides a comprehensive event system that works across all protocols:
 
-#### 1. Lifecycle Events (All Protocols)
+#### 1. Lifecycle Events
 
-These are internal ability lifecycle events that work across all protocols:
+Monitor the ability lifecycle:
 
 ```javascript
-const ability = new KadiAbility({ name: 'events-ability' });
+const client = new KadiClient({ name: 'my-ability' });
 
-// Listen to lifecycle events
-ability.on('start', ({ protocol, methods }) => {
-  console.log(`Started with ${protocol}, methods: ${methods.join(', ')}`);
+// Connection events
+client.on('connected', ({ broker }) => {
+  console.log(`Connected to broker: ${broker}`);
 });
 
-ability.on('request', ({ id, method, params }) => {
-  console.log(`Request ${id}: ${method}`);
+client.on('disconnected', () => {
+  console.log('Disconnected from broker');
 });
 
-ability.on('response', ({ id, result, error }) => {
-  if (error) console.error(`Error in ${id}:`, error);
-  else console.log(`Response ${id}:`, result);
+// Tool invocation events
+client.on('tool:invoked', ({ toolName, params }) => {
+  console.log(`Tool ${toolName} invoked with:`, params);
 });
 
-ability.on('error', (error) => {
+client.on('tool:completed', ({ toolName, result }) => {
+  console.log(`Tool ${toolName} completed:`, result);
+});
+
+client.on('error', (error) => {
   console.error('Ability error:', error);
 });
 ```
 
-#### 2. Custom Events (Native and Stdio Protocols Only - for now)
+#### 2. Custom Events (All Protocols)
 
-Abilities can publish custom events that agents can subscribe to:
+Publish and subscribe to custom events across all transport protocols:
 
 ```javascript
-// In your ability
-const ability = new KadiAbility({ name: 'my-ability' });
+// Publishing events
+const publisher = new KadiClient({
+  name: 'event-publisher',
+  role: 'ability',
+  protocol: 'broker' // Works with all protocols
+});
 
-ability.method('process', async ({ data }) => {
+publisher.registerTool('process', async ({ data }) => {
   // Publish events during processing
-  ability.publishEvent('process:started', {
-    timestamp: new Date().toISOString()
+  await publisher.publishEvent('process.started', {
+    timestamp: Date.now(),
+    data
   });
 
-  // ... do work ...
+  // Do work...
+  const result = await processData(data);
 
-  ability.publishEvent('process:completed', {
-    result: 'success',
-    timestamp: new Date().toISOString()
+  await publisher.publishEvent('process.completed', {
+    timestamp: Date.now(),
+    result
   });
 
-  return { processed: data };
+  return result;
 });
 
-// In your agent (index.js)
-const ability = await loadAbility('my-ability');
+// Subscribing to events
+const subscriber = new KadiClient({
+  name: 'event-subscriber',
+  role: 'agent',
+  protocol: 'broker'
+});
 
-// Subscribe to custom events BEFORE calling methods
-ability.events.on('process:started', (data) => {
-  console.log(`Process started at: ${data.timestamp}`);
+// Subscribe with wildcards
+subscriber.subscribeToEvent('process.*', (data) => {
+  console.log('Process event:', data);
 });
 
-ability.events.on('process:completed', (data) => {
-  console.log(`Process completed: ${data.result} at ${data.timestamp}`);
+// One-time subscription
+subscriber.onceEvent('process.completed', (data) => {
+  console.log('First completion:', data);
 });
 
-// Now call the method that emits events
-await ability.process({ data: 'test' });
+// Multiple pattern subscription
+subscriber.subscribeToEvents(['process.*', 'system.*'], (pattern, data) => {
+  console.log(`Event from ${pattern}:`, data);
+});
 ```
 
-**Important Notes:**
+**Protocol-Specific Behavior:**
+
+- **Native**: Direct EventEmitter, synchronous delivery
+- **Stdio**: JSON-RPC notifications with LSP framing
+- **Broker**: RabbitMQ pub/sub via WebSocket, persistent queues available
+
+### Multi-Broker Configuration
+
+KadiClient supports connecting to multiple brokers simultaneously for redundancy and load distribution:
+
+```javascript
+const client = new KadiClient({
+  name: 'multi-broker-ability',
+  role: 'ability',
+  protocol: 'broker',
+  brokers: {
+    'primary': 'ws://broker1.example.com:8080',
+    'secondary': 'ws://broker2.example.com:8080',
+    'backup': 'ws://broker3.example.com:8080'
+  },
+  defaultBroker: 'primary', // Used for sending if no specific broker targeted
+  networks: ['production']
+});
+
+// Connect to all configured brokers
+await client.connectToBrokers();
 
-- Custom events only work with `native` and `stdio` protocols for now
-- Always subscribe to events before calling methods that emit them
-- Events are emitted immediately when `publishEvent()` is called
-- Broker protocol event support is in progress
+// The client will now:
+// 1. Maintain connections to all three brokers
+// 2. Receive messages from any broker
+// 3. Send messages to the default broker unless specified
+// 4. Automatically handle broker failover
+```
+
+### Cross-Language Ability Support
 
-### Error Handling
+KADI now fully supports abilities written in any language through the stdio protocol:
 
 ```javascript
-try {
-  const ability = await loadAbility('my-ability', 'stdio');
-  const result = await ability.riskyMethod({ data: 'test' });
-} catch (error) {
-  if (error.message.includes('not found')) {
-    console.error('Ability not installed. Run: kadi install');
-  } else if (error.message.includes('timeout')) {
-    console.error('Method timed out. Check ability health.');
-  } else if (error.message.includes('not exposed by this ability')) {
-    console.error(
-      'Method not available. Use ability.__list() to see available methods.'
-    );
-  } else {
-    console.error('Unexpected error:', error);
+// Go ability with agent.json:
+{
+  "name": "hash-go",
+  "scripts": {
+    "setup": "go build -o bin/hash_ability",
+    "start": "./bin/hash_ability"  // Binary executable
+  }
+}
+
+// Python ability:
+{
+  "name": "ml-processor",
+  "scripts": {
+    "start": "python3 main.py"
   }
 }
+
+// Rust ability:
+{
+  "name": "crypto-rust",
+  "scripts": {
+    "setup": "cargo build --release",
+    "start": "./target/release/crypto_ability"
+  }
+}
+
+// Load and use regardless of implementation language:
+const hashAbility = await loadAbility('hash-go', 'stdio');
+const result = await hashAbility.sha256({ data: 'hello' });
 ```
 
 ## 🔧 Development Workflow
@@ -772,7 +1028,7 @@ try {
 
 When developing new features or testing changes to `@kadi.build/core` before publishing to NPM:
 
-0. **clone the repository**
+0. **Clone the repository**
 
 ```bash
 git clone https://gitlab.com/humin-game-lab/kadi/kadi-core.git
@@ -786,14 +1042,14 @@ npm pack
 # This creates: kadi.build-core-X.Y.Z.tgz
 ```
 
-1. **Install in your project**:
+2. **Install in your project**:
 
 ```bash
 cd /path/to/your-project
 npm install /path/to/kadi-core/kadi.build-core-X.Y.Z.tgz
 ```
 
-1. **For ability development**, update the ability's preflight script:
+3. **For ability development**, update the ability's preflight script:
 
 ```json
 {
@@ -807,402 +1063,295 @@ npm install /path/to/kadi-core/kadi.build-core-X.Y.Z.tgz
 
 ### Core Classes
 
-#### `KadiAbility`
+#### `KadiClient`
 
-The main class for creating abilities.
+The unified class for all KADI operations - serving tools, calling remote abilities, and managing events.
 
 ```javascript
-import { KadiAbility } from '@kadi.build/core';
+import { KadiClient } from '@kadi.build/core';
 
-const ability = new KadiAbility({
+const client = new KadiClient({
   name: 'my-ability',
-  version: '1.0.0',
-  description: 'My ability description',
-  scope: 'global', // or process.env.KADI_AGENT_SCOPE
-  protocol: 'stdio' // 'native', 'stdio', or 'broker'
+  role: 'ability', // 'agent' or 'ability'
+  protocol: 'broker', // 'native', 'stdio', or 'broker'
+  brokers: {
+    'dev': 'ws://localhost:8080',
+    'prod': 'ws://prod.example.com:8080'
+  },
+  defaultBroker: 'dev',
+  network: 'global', // Primary network
+  networks: ['global', 'custom-network'] // All networks
 });
 ```
 
-**Methods:**
-
-- `ability.method(name, handler, schema?)` - Register a method
-- `ability.serve()` - Start serving requests
-- `ability.publishEvent(eventName, data)` - Publish an event
-- `ability.on(event, handler)` - Listen to lifecycle events
-
-#### `loadAbility`
-
-Load an ability by name and protocol.
-
-```javascript
-import { loadAbility } from '@kadi.build/core';
-
-const ability = await loadAbility('ability-name', 'protocol');
-```
-
-**Returns:** A proxy object with:
+**Configuration Options:**
 
-- Direct method calls (e.g., `ability.echo({ message: 'hello' })`)
-- `ability.__list()` - List available methods
-- `ability.events` - EventEmitter for subscribing to events (native/stdio protocols only)
-- `ability.call(method, params)` - Direct RPC call
+- `name` - Ability/agent name
+- `role` - Operating role: 'agent' (consumer) or 'ability' (provider)
+- `protocol` - Transport protocol to use
+- `brokers` - Named broker configurations (object mapping names to URLs)
+- `defaultBroker` - Default broker name for sending messages
+- `network` - Primary network segment for message routing
+- `networks` - All network namespaces for tool discovery
+- `heartbeatIntervalSec` - Custom heartbeat interval (default: from broker)
 
-### Utility Functions
+**Tool Registration Methods:**
 
-```javascript
-import {
-  createLogger,
-  getProjectJSON,
-  getAbilityJSON,
-  getBrokerUrl,
-  runExecCommand
-} from '@kadi.build/core';
-```
+- `registerTool(name, handler, schema?)` - Register a single tool
+- `getTools()` - Get list of registered tool names
+- `getToolNames()` - Get filtered list of tool names
+- `getToolHandler(name)` - Get a specific tool's handler
+- `getToolSchema(name)` - Get a specific tool's schema
+- `hasTool(name)` - Check if a tool is registered
 
-## 🎮 Running the Examples
+**Remote Tool Invocation:**
 
-### Quick Start with Example Agent
+- `callTool(targetAgent, toolName, params)` - Call a remote tool via broker
+- `discoverRemoteTools(targetAgent)` - List tools from a remote agent
+- `loadAbility(name, protocol?, options?)` - Load an ability (compatibility)
 
-The `@kadi.build/core` package includes a complete example demonstrating multi-language abilities (JavaScript and Go) with all three transport protocols.
+**Event System:**
 
-The `examples` folder contains:
+- `publishEvent(eventName, data)` - Publish an event
+- `subscribeToEvent(pattern, callback)` - Subscribe with wildcards
+- `subscribeToEvents(patterns[], callback)` - Multiple subscriptions
+- `unsubscribeFromEvent(pattern, callback)` - Remove subscription
+- `onceEvent(pattern, callback)` - One-time subscription
 
-```
-examples/
-├── example-abilities/       # Sample abilities in different languages
-│   ├── echo-js/            # JavaScript ability using KadiAbility
-│   │   ├── agent.json      # Ability configuration
-│   │   ├── service.js      # Implementation
-│   │   └── package.json
-│   └── hash-go/            # Go ability demonstrating polyglot support
-│       ├── agent.json
-│       ├── go.mod
-│       └── cmd/hash_ability/main.go
-└── example-agent/          # Sample agent using the abilities
-    ├── agent.json          # Declares dependencies on abilities
-    ├── index.js            # Demonstrates all loading patterns
-    └── package.json
-```
+**Connection Management:**
 
-#### Step 0: Have the KADI broker running locally
+- `serve()` - Start serving (stdio/native modes)
+- `connectToBrokers()` - Connect to all configured brokers
+- `disconnect()` - Clean disconnect
+- `isConnected` - Check connection status
 
-```bash
-kadi broker up
-```
+**Properties:**
 
-#### Step 1: Navigate to the example agent
-
-```bash
-cd /path/to/kadi-core/examples/example-agent
-```
-
-#### Step 2: Install abilities
-
-```bash
-# Inside 'example-agent' folder
-kadi install
-```
-
-This installs the `echo-js` (JavaScript) and `hash-go` (Go) abilities defined in the agent.json.
-
-#### Step 3: Run the agent
-
-```bash
-kadi run
-```
-
-#### Expected Output
-
-You should see the agent testing various abilities and protocols:
-
-```
-=== WORKING ABILITIES ===
-
-🔧 Loading echo-js ability using native (Javascript)...
-Available methods: [ 'echo', 'say_message' ]
-Echo-js echo result: {
-  echo: 'I am calling echo-js echo method from Javascript',
-  timestamp: '2025-08-15T00:20:23.276Z',
-  length: 48
-}
-
-🔧 Loading echo-js ability using stdio (Javascript)...
-Available methods: [ 'echo', 'say_message' ]
-Echo-js echo result: {
-  echo: 'I am calling echo-js echo method from Javascript',
-  timestamp: '2025-08-15T00:20:23.339Z',
-  length: 48
-}
-```
+- `agentId` - Unique agent identifier
+- `name` - Ability name
+- `role` - Current operating role
+- `protocol` - Active protocol
+- `brokers` - Configured broker map
+- `defaultBroker` - Default broker name
+- `currentBroker` - Currently active broker for sending
 
-#### Step 4: Stop and Clean Up
-
-```bash
-# Stop the agent
-Ctrl + C
-
-# Clean up installed abilities and node_modules
-kadi run clean
-```
-
-### What the Example Demonstrates
-
-1. **Polyglot Abilities**: Go (`hash-go`) and JavaScript (`echo-js`) abilities working together
-2. **Protocol Flexibility**: Same ability (`echo-js`) loaded via native, stdio, and broker
-3. **Error Handling**: Graceful handling when calling non-existent methods
-4. **Method Discovery**: Using `__list()` to discover available methods
-5. **Schema Support**: Both inline and export-based schema definitions
-6. **Event System**: Publishing and subscribing to events across protocols
-7. **Event Timing**: Demonstrates the importance of subscribing to events before calling methods
-
-### Exploring the Code
-
-**echo-js ability** (`examples/example-abilities/echo-js/service.js`):
-
-- Shows method registration with and without schemas
-- Demonstrates scope configuration for broker visibility
-- Uses environment variables for protocol adaptation
-- Includes event publishing examples using `publishEvent()`
-- Demonstrates how to emit events from method handlers
-
-**hash-go ability** (`examples/example-abilities/hash-go/`):
-
-- Demonstrates Go SDK integration
-- Shows stdio protocol with a compiled language
-- Implements SHA256 hashing as a service
-
-**example-agent** (`examples/example-agent/index.js`):
-
-- Shows all three loading patterns
-- Demonstrates error handling
-- Tests cross-language ability communication
-- Includes event subscription examples using `ability.events.on()`
-- Shows how to subscribe to events before calling methods
-- Demonstrates event handling across different protocols (native/stdio)
-
-## 💡 Additional Examples
-
-### Complete Echo Service Example
-
-**service.js**:
+**Complete Usage Example:**
 
 ```javascript
-#!/usr/bin/env node
-import { KadiAbility } from '@kadi.build/core';
+import { KadiClient } from '@kadi.build/core';
 
-const echoAbility = new KadiAbility({
-  name: 'echo-service',
-  version: '1.0.0',
-  description: 'Multi-protocol echo service',
-  scope: process.env.KADI_AGENT_SCOPE // Important for broker visibility
-});
-
-// Simple echo with metadata
-echoAbility.method('echo', async ({ message }) => {
-  // Publish events (works for native and stdio protocols)
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo' });
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo 2' });
-
-  return {
-    echo: message,
-    timestamp: new Date().toISOString(),
-    length: message?.length || 0
-  };
+// Create an ability that can serve tools
+const ability = new KadiClient({
+  name: 'math-ability',
+  role: 'ability',
+  protocol: 'broker',
+  brokers: {
+    'local': 'ws://localhost:8080',
+    'cloud': 'wss://api.example.com'
+  },
+  defaultBroker: 'local',
+  networks: ['global']
 });
 
-// Transform text
-echoAbility.method(
-  'transform',
-  async ({ text, operations }) => {
-    let result = text;
-    for (const op of operations) {
-      switch (op) {
-        case 'upper':
-          result = result.toUpperCase();
-          break;
-        case 'lower':
-          result = result.toLowerCase();
-          break;
-        case 'reverse':
-          result = result.split('').reverse().join('');
-          break;
-      }
-    }
-    return { transformed: result };
+// Register tools with schemas
+ability.registerTool(
+  'add',
+  async ({ a, b }) => {
+    // Publish event before processing
+    await ability.publishEvent('math.operation', {
+      operation: 'add',
+      inputs: { a, b }
+    });
+
+    const result = a + b;
+
+    // Publish completion event
+    await ability.publishEvent('math.completed', {
+      operation: 'add',
+      result
+    });
+
+    return { result };
   },
   {
-    description: 'Transform text with multiple operations',
+    description: 'Add two numbers',
     inputSchema: {
       type: 'object',
       properties: {
-        text: { type: 'string' },
-        operations: {
-          type: 'array',
-          items: { enum: ['upper', 'lower', 'reverse'] }
-        }
+        a: { type: 'number', description: 'First number' },
+        b: { type: 'number', description: 'Second number' }
       },
-      required: ['text', 'operations']
+      required: ['a', 'b']
+    },
+    outputSchema: {
+      type: 'object',
+      properties: {
+        result: { type: 'number', description: 'Sum of a and b' }
+      }
     }
   }
 );
 
-echoAbility.serve().catch(console.error);
-```
-
-**Using the service**:
+// Subscribe to events from other abilities
+ability.subscribeToEvent('system.*', (data) => {
+  console.log('System event:', data);
+});
 
-```javascript
-import { loadAbility } from '@kadi.build/core';
+// Connect to brokers
+await ability.connectToBrokers();
 
-async function demo() {
-  // Try all protocols
-  for (const protocol of ['native', 'stdio', 'broker']) {
-    console.log(`\nTesting ${protocol} protocol:`);
-
-    try {
-      const echo = await loadAbility('echo-service', protocol);
-
-      // Subscribe to events (works for native and stdio protocols)
-      echo.events.on('echo:test-event', (data) => {
-        console.log(`Echo event received: ${data.from}`);
-      });
-
-      // Simple echo
-      const result1 = await echo.echo({
-        message: `Hello from ${protocol}!`
-      });
-      console.log('Echo:', result1);
-
-      // Transform
-      const result2 = await echo.transform({
-        text: 'Hello World',
-        operations: ['lower', 'reverse']
-      });
-      console.log('Transform:', result2);
-    } catch (error) {
-      console.error(`${protocol} failed:`, error.message);
-    }
-  }
-}
+// Call remote tools
+const result = await ability.callTool('translator-ability', 'translate', {
+  text: 'Hello',
+  to: 'es'
+});
 
-demo();
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await ability.disconnect();
+  process.exit(0);
+});
 ```
 
-## 🎯 Real-World Event Example
-
-Here's the exact event pattern used in the example code:
+#### `loadAbility`
 
-**In your ability (service.js):**
+Load an ability by name and protocol.
 
 ```javascript
-const echoAbility = new KadiAbility({
-  name: 'echo-js',
-  version: '0.0.1',
-  scope: process.env.KADI_AGENT_SCOPE
-});
-
-async function echo(message) {
-  const timestamp = new Date().toISOString();
-  const messageText = message?.message ?? message ?? '';
-  const length = messageText.length;
+import { loadAbility } from '@kadi.build/core';
 
-  // Publish events (works for native and stdio protocols)
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo' });
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo 2' });
+const ability = await loadAbility('ability-name', 'protocol', {
+  brokerUrl: 'ws://localhost:8080', // For broker protocol
+  brokerName: 'dev', // Named broker to use
+  networks: ['global'], // Network segments
+  existingClient: client // Reuse existing KadiClient for broker
+});
+```
 
-  return { echo: messageText, timestamp, length };
-}
+**Returns:** A proxy object with:
 
-echoAbility.method('echo', echo);
-```
+- Direct method calls (e.g., `ability.echo({ message: 'hello' })`)
+- `ability.events` - EventEmitter for subscribing to events (all protocols)
+- `ability.__call(method, params)` - Direct RPC call
+- `ability.__disconnect()` - Clean up resources
 
-**In your agent (index.js):**
+### Utility Functions
 
 ```javascript
-// Subscribe first
-echoJsAbility.events.on('echo:test-event', (data) => {
-  console.log(`[NATIVE] echo:test-event received:`, data);
-});
-
-// Now trigger the method that emits the event
-const echoJsResult = await echoJsAbility.echo({
-  message: 'I am calling echo-js echo method from Javascript'
-});
+import {
+  createLogger,
+  getProjectJSON,
+  getAbilityJSON,
+  getAgentJSON,
+  getBrokerUrl,
+  runExecCommand
+} from '@kadi.build/core';
 ```
 
-**Key Points:**
-
-- Events work for `native` and `stdio` protocols only
-- Always subscribe to events BEFORE calling methods that emit them
-- Events are emitted immediately when `publishEvent()` is called
-- Use `ability.events.on()` to subscribe to custom events
-- Use `ability.on()` to listen to lifecycle events
+### Debug Mode
 
-## 🐛 Troubleshooting
+Enable detailed logging:
 
-### Common Issues
+```bash
+DEBUG=kadi:* node index.js
+```
 
-**Ability Not Found**
+Check ability logs:
 
+```bash
+tail -f abilities/my-ability/1.0.0/my-ability.log
 ```
-Error: Ability 'my-ability' version '1.0.0' is not installed
-```
+## 💡 Additional Examples
 
-**Solution**: Run `kadi install` to install project dependencies
+### Error Handling Pattern
 
-**Broker Connection Failed**
+```javascript
+const client = new KadiClient({
+  name: 'robust-ability',
+  role: 'ability'
+});
 
-```
-Error: Failed to connect to KADI Broker at ws://localhost:8080
+client.registerTool('riskyOperation', async (params) => {
+  try {
+    const result = await performOperation(params);
+    await client.publishEvent('operation.success', { result });
+    return { success: true, result };
+  } catch (error) {
+    await client.publishEvent('operation.error', {
+      error: error.message,
+      params
+    });
+    // Return error in structured format
+    return {
+      success: false,
+      error: error.message
+    };
+  }
+});
 ```
 
-**Solution**: Ensure the broker is running: `kadi broker start`
+### Health Check Pattern
 
-**Method Not Found**
-
-```
-Error: Method 'someMethod' is not exposed by this ability
+```javascript
+// Register a standard health check tool
+client.registerTool('health', async () => {
+  const checks = {
+    memory: process.memoryUsage(),
+    uptime: process.uptime(),
+    brokers: client.isConnected ? 'connected' : 'disconnected',
+    timestamp: Date.now()
+  };
+  
+  return {
+    status: 'healthy',
+    checks
+  };
+});
 ```
 
-**Solution**: Check ability exports or use `__list()` to see available methods
+## 🐛 Troubleshooting
 
-**Protocol Not Supported**
+### Common Issues and Solutions
 
-```
-Error: Unsupported ability interface protocol: custom
-```
+#### Broker Connection Failures
 
-**Solution**: Ability must define the protocol in its `agent.json` interfaces
+**Problem**: "Failed to connect to any brokers"
 
-**Event Subscription Issues**
+**Solutions**:
+- Verify broker URLs are correct
+- Check network connectivity
+- Ensure broker is running
+- Try connecting with lower security (ws:// before wss://)
 
-```
-TypeError: Cannot read property 'on' of undefined
-```
-
-**Solution**: Make sure you're accessing `ability.events.on()` not `ability.on()` for custom events
+#### Events Not Arriving
 
-**Event Protocol Support**
+**Problem**: Subscribed to events but callbacks not triggered
 
-```
-Events are only supported for 'native' and 'stdio' protocols
-```
+**Solutions**:
+- Subscribe BEFORE triggering events
+- Check pattern matching (use exact match first)
+- Verify publisher and subscriber are on same network
+- Enable debug logging to trace event flow
 
-**Solution**: Events currently work for `native` and `stdio` protocols only. Broker protocol event support is planned for future releases.
+#### Cross-Language Abilities Not Loading
 
-### Debug Mode
+**Problem**: "Cannot find module 'ability.js'" when loading Go/Python abilities
 
-Enable detailed logging:
+**Solutions**:
+- Ensure `scripts.start` field exists in agent.json
+- Verify the binary/script is executable
+- Check that setup script has been run
+- Use stdio protocol, not native
 
-```bash
-DEBUG=kadi:* node index.js
-```
+#### Memory Leaks
 
-Check ability logs:
+**Problem**: Memory usage grows over time
 
-```bash
-tail -f abilities/my-ability/1.0.0/my-ability.log
-```
+**Solutions**:
+- Always call unsubscribe functions
+- Use `onceEvent` for single-use subscriptions
+- Disconnect abilities when done
+- Clear event listeners on cleanup
 
 ## 🤝 Contributing
 
@@ -1216,7 +1365,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 
 ## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## 🔗 Related Projects
 
@@ -1225,11 +1374,10 @@ MIT License - see [LICENSE](LICENSE) file for details
 
 ## 📚 Resources
 
-- [Official Documentation](https://docs.kadi.build)
-- [API Reference](https://docs.kadi.build/api)
-- [Tutorial: Building Your First Ability](https://docs.kadi.build/tutorial)
-- [Architecture Deep Dive](https://docs.kadi.build/architecture)
+- [Event System Deep Dive](docs/event-system.md) - Complete guide to the event architecture
+- [API Documentation](https://docs.kadi.build) - Full API reference
+- [Examples Repository](https://github.com/kadi-examples) - More examples and patterns
 
 ---
 
-Built with ❤️ by the KADI team
+Built with ❤️ by the KADI team