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

package/README.md

@@ -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,26 +45,32 @@ npm install -g @kadi.build/cli
 
 ## 🚀 Quick Start
 
-### Creating Your First Ability
+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
+- **As a Service**: Combining both roles - serving and consuming tools
+
+### Creating Your First Service
 
 ```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({
-  name: 'math-ability',
-  version: '1.0.0',
-  description: 'Simple math operations'
+// Create a service instance
+const mathService = new KadiClient({
+  name: 'math-service',
+  role: 'ability', // 'agent', 'ability', or 'service'
+  protocol: 'stdio' // 'native', 'stdio', or 'broker'
 });
 
-// Register a method
-mathAbility.method('add', async ({ a, b }) => {
+// Register a tool
+mathService.registerTool('add', async ({ a, b }) => {
   return { result: a + b };
 });
 
 // Start serving requests
-mathAbility.serve().catch(console.error);
+mathService.serve().catch(console.error);
 ```
 
 ### Loading and Using Abilities
@@ -78,14 +85,54 @@ 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',
+  brokerUrls: ['ws://localhost:8080'],
+  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 broker 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:
@@ -185,28 +232,28 @@ graph TD
 }
 ```
 
-## 🛠️ Creating Abilities
+## 🛠️ Creating Services with KadiClient
 
-### Basic Ability Structure
+### Basic Service Structure
 
 ```javascript
-import { KadiAbility } from '@kadi.build/core';
+import { KadiClient } from '@kadi.build/core';
 
-const ability = new KadiAbility({
-  name: 'echo-ability',
-  version: '1.0.0',
-  description: 'Echo service with metadata',
-  scope: process.env.KADI_AGENT_SCOPE || 'global'
+const service = new KadiClient({
+  name: 'echo-service',
+  role: 'ability',  // 'agent', 'ability', or 'service'
+  protocol: 'stdio', // 'native', 'stdio', or 'broker'
+  brokerUrls: ['ws://localhost:8080'] 
 });
 
-// Method 1: Simple handler
-ability.method('echo', async ({ message }) => ({
+// Method 1: Simple tool registration
+service.registerTool('echo', async ({ message }) => ({
   echo: message,
   timestamp: new Date().toISOString()
 }));
 
-// Method 2: Handler with inline schema
-ability.method(
+// Method 2: Tool with inline schema
+service.registerTool(
   'format',
   async ({ text, style }) => ({
     formatted: style === 'upper' ? text.toUpperCase() : text.toLowerCase()
@@ -235,41 +282,60 @@ ability.method(
 );
 
 // Start serving
-ability.serve().catch(console.error);
+service.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' });
-
-// 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' });
+// In your service (service.js)
+const service = new KadiClient({ 
+  name: 'my-service',
+  role: 'ability',
+  protocol: 'broker' // Works with all protocols
+});
 
-  return { echo: message, timestamp: new Date().toISOString() };
+// Publish events from tool handlers
+service.registerTool('echo', async ({ message }) => {
+  // Publish events during processing
+  await service.publishEvent('echo.processing', { status: 'started' });
+  
+  // Do work...
+  const result = { echo: message, timestamp: new Date().toISOString() };
+  
+  await service.publishEvent('echo.completed', { result });
+  return result;
 });
 
-// In your agent (index.js)
-const ability = await loadAbility('my-ability');
+// In your client (index.js)
+const client = 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
+client.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-service', '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)
 
@@ -361,176 +427,322 @@ 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 remoteService = await loadAbility('remote-service', 'broker', {
+  brokerUrl: 'ws://localhost:8080',
+  networks: ['global']
+});
+const brokerResult = await remoteService.process({ data: 'test' });
+```
+
+### Using KadiClient
+
+```javascript
+import { KadiClient } from '@kadi.build/core';
+
+// Create a unified client
+const client = new KadiClient({
+  name: 'my-service',
+  role: 'service', // Can both serve and consume
+  protocol: 'broker',
+  brokerUrls: ['ws://localhost:8080'],
+  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 and serve
+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 service 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 Service
     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->>Service: Extract tool handlers via getToolNames()
+        Service-->>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->>Service: KadiClient detects stdio mode
+        Service->>Service: Setup FrameReader/Writer
+        Transport->>Service: Send discovery request
+        Service-->>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: Create KadiClient wrapper
+        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,Service: Tool invocation
+    Client->>Transport: ability.echo({ message })
+    
+    alt native
+        Transport->>Service: Direct handler call
+    else stdio  
+        Transport->>Service: JSON-RPC over frames
+    else broker
+        Transport->>Broker: kadi.ability.invoke
+        Broker->>Service: Route to target
+        Service->>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,KC: Tool Registration Phase
+    Dev->>KC: new KadiClient({ name, role, protocol })
+    KC->>KC: Initialize based on role & protocol
+    
+    Dev->>KC: registerTool('echo', handler, schema?)
+    KC->>KC: Store in toolHandlers Map<name, {handler, schema}>
+    
+    Dev->>KC: registerTool('process', handler, schema)
+    KC->>KC: Add to toolHandlers Map
+
+    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'
+        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
 
-    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 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
+    
+    Network-->>RemoteClient: Tool result
+```
 
-    Dev->>KA: ability.method('transform', handler, schema)
-    KA->>KA: Store handler in methodHandlers
-    KA->>KA: Store schema in methodMCPSchemas
+### Event System Architecture
 
-    Note over KA,Transport: Serving Phase
-    Dev->>KA: ability.serve()
-    KA->>KA: Detect protocol from env/options
+KadiClient provides a unified event API that works across all transport protocols:
 
-    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
+```mermaid
+sequenceDiagram
+    participant Publisher as Service (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'
-        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 })
+        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
-
-    Server->>KA: Forward events (start, request, response, error)
-
-    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
 ```
 
 ### 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 Service
+    
+    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('service-b', 'process', params)
+    Client->>Broker: kadi.ability.invoke({ 
+        targetAgent: 'service-b',
+        toolName: 'process',
+        toolInput: params
+    })
+    Broker->>Broker: Lookup service-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
@@ -590,9 +802,8 @@ 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' });
@@ -638,9 +849,9 @@ 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 serviceName = process.env.KADI_SERVICE_NAME; 
+const agentScope = process.env.KADI_AGENT_SCOPE;
 
 // Use them to configure your ability behavior
 const ability = new KadiAbility({
@@ -650,7 +861,7 @@ const ability = new KadiAbility({
 });
 ```
 
-### Project Structure
+### Example Project Structure
 
 ```
 my-project/
@@ -670,101 +881,100 @@ 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 service lifecycle:
 
 ```javascript
-const ability = new KadiAbility({ name: 'events-ability' });
+const client = new KadiClient({ name: 'my-service' });
+
+// Connection events
+client.on('connected', ({ broker }) => {
+  console.log(`Connected to broker: ${broker}`);
+});
 
-// Listen to lifecycle events
-ability.on('start', ({ protocol, methods }) => {
-  console.log(`Started with ${protocol}, methods: ${methods.join(', ')}`);
+client.on('disconnected', () => {
+  console.log('Disconnected from broker');
 });
 
-ability.on('request', ({ id, method, params }) => {
-  console.log(`Request ${id}: ${method}`);
+// Tool invocation events
+client.on('tool:invoked', ({ toolName, params }) => {
+  console.log(`Tool ${toolName} invoked with:`, params);
 });
 
-ability.on('response', ({ id, result, error }) => {
-  if (error) console.error(`Error in ${id}:`, error);
-  else console.log(`Response ${id}:`, result);
+client.on('tool:completed', ({ toolName, result }) => {
+  console.log(`Tool ${toolName} completed:`, result);
 });
 
-ability.on('error', (error) => {
-  console.error('Ability error:', error);
+client.on('error', (error) => {
+  console.error('Service 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: 'service',
+  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:**
-
-- 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
+**Protocol-Specific Behavior:**
 
-### Error Handling
+- **Native**: Direct EventEmitter, synchronous delivery
+- **Stdio**: JSON-RPC notifications with LSP framing
+- **Broker**: RabbitMQ pub/sub via WebSocket, persistent queues available
 
-```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);
-  }
-}
-```
 
 ## 🔧 Development Workflow
 
@@ -807,388 +1017,164 @@ 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 services, and managing events.
 
 ```javascript
-import { KadiAbility } from '@kadi.build/core';
-
-const ability = new KadiAbility({
-  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'
+import { KadiClient } from '@kadi.build/core';
+
+const client = new KadiClient({
+  name: 'my-service',
+  role: 'service', // 'agent', 'ability', or 'service'
+  protocol: 'broker', // 'native', 'stdio', or 'broker'
+  brokerUrls: ['ws://localhost:8080'],
+  networks: ['global', 'custom-network']
 });
 ```
 
-**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:
-
-- 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
-
-### Utility Functions
+**Configuration Options:**
+- `name` - Service/agent name
+- `role` - Operating role: 'agent' (consumer), 'ability' (provider), 'service' (both)
+- `protocol` - Transport protocol to use
+- `brokerUrls` - Array of broker WebSocket URLs (for broker protocol)
+- `networks` - Network namespaces for tool discovery
+- `heartbeatIntervalSec` - Custom heartbeat interval (default: from broker)
+
+**Tool Registration Methods:**
+- `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
+
+**Remote Tool Invocation:**
+- `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)
+
+**Event System:**
+- `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
+
+**Connection Management:**
+- `serve()` - Start serving (stdio/native modes)
+- `connectToBrokers(urls?)` - Connect to broker(s)
+- `disconnect()` - Clean disconnect
+- `isConnected` - Check connection status
+
+**Properties:**
+- `agentId` - Unique agent identifier
+- `name` - Service name
+- `role` - Current operating role
+- `protocol` - Active protocol
+
+**Complete Usage Example:**
 
 ```javascript
-import {
-  createLogger,
-  getProjectJSON,
-  getAbilityJSON,
-  getBrokerUrl,
-  runExecCommand
-} from '@kadi.build/core';
-```
-
-## 🎮 Running the Examples
-
-### Quick Start with Example Agent
-
-The `@kadi.build/core` package includes a complete example demonstrating multi-language abilities (JavaScript and Go) with all three transport protocols.
-
-The `examples` folder contains:
-
-```
-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
-```
-
-#### Step 0: Have the KADI broker running locally
-
-```bash
-kadi broker up
-```
-
-#### 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
-}
-```
-
-#### 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**:
-
-```javascript
-#!/usr/bin/env node
-import { KadiAbility } 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
-  };
+import { KadiClient } from '@kadi.build/core';
+
+// Create a service that can both serve and consume
+const service = new KadiClient({
+  name: 'math-service',
+  role: 'service',
+  protocol: 'broker',
+  brokerUrls: ['ws://localhost:8080'],
+  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
+service.registerTool(
+  'add',
+  async ({ a, b }) => {
+    // Publish event before processing
+    await service.publishEvent('math.operation', {
+      operation: 'add',
+      inputs: { a, b }
+    });
+    
+    const result = a + b;
+    
+    // Publish completion event
+    await service.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**:
-
-```javascript
-import { loadAbility } from '@kadi.build/core';
-
-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);
-    }
-  }
-}
-
-demo();
-```
-
-## 🎯 Real-World Event Example
-
-Here's the exact event pattern used in the example code:
-
-**In your ability (service.js):**
-
-```javascript
-const echoAbility = new KadiAbility({
-  name: 'echo-js',
-  version: '0.0.1',
-  scope: process.env.KADI_AGENT_SCOPE
+// Subscribe to events from other services
+service.subscribeToEvent('system.*', (data) => {
+  console.log('System event:', data);
 });
 
-async function echo(message) {
-  const timestamp = new Date().toISOString();
-  const messageText = message?.message ?? message ?? '';
-  const length = messageText.length;
-
-  // 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: messageText, timestamp, length };
-}
-
-echoAbility.method('echo', echo);
-```
-
-**In your agent (index.js):**
+// Connect to broker
+await service.connectToBrokers();
 
-```javascript
-// Subscribe first
-echoJsAbility.events.on('echo:test-event', (data) => {
-  console.log(`[NATIVE] echo:test-event received:`, data);
-});
+// Call remote tools
+const result = await service.callTool(
+  'translator-service',
+  'translate',
+  { text: 'Hello', to: 'es' }
+);
 
-// Now trigger the method that emits the event
-const echoJsResult = await echoJsAbility.echo({
-  message: 'I am calling echo-js echo method from Javascript'
+// Graceful shutdown
+process.on('SIGTERM', async () => {
+  await service.disconnect();
+  process.exit(0);
 });
 ```
 
-**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
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Ability Not Found**
-
-```
-Error: Ability 'my-ability' version '1.0.0' is not installed
-```
-
-**Solution**: Run `kadi install` to install project dependencies
-
-**Broker Connection Failed**
-
-```
-Error: Failed to connect to KADI Broker at ws://localhost:8080
-```
-
-**Solution**: Ensure the broker is running: `kadi broker start`
-
-**Method Not Found**
-
-```
-Error: Method 'someMethod' is not exposed by this ability
-```
+#### `loadAbility`
 
-**Solution**: Check ability exports or use `__list()` to see available methods
+Load an ability by name and protocol.
 
-**Protocol Not Supported**
+```javascript
+import { loadAbility } from '@kadi.build/core';
 
-```
-Error: Unsupported ability interface protocol: custom
+const ability = await loadAbility('ability-name', 'protocol');
 ```
 
-**Solution**: Ability must define the protocol in its `agent.json` interfaces
-
-**Event Subscription Issues**
-
-```
-TypeError: Cannot read property 'on' of undefined
-```
+**Returns:** A proxy object with:
 
-**Solution**: Make sure you're accessing `ability.events.on()` not `ability.on()` for custom events
+- Direct method calls (e.g., `ability.echo({ message: 'hello' })`)
+- `ability.events` - EventEmitter for subscribing to events (native/stdio protocols only)
+- `ability.__call(method, params)` - Direct RPC call
 
-**Event Protocol Support**
+### Utility Functions
 
+```javascript
+import {
+  createLogger,
+  getProjectJSON,
+  getAbilityJSON,
+  getBrokerUrl,
+  runExecCommand
+} from '@kadi.build/core';
 ```
-Events are only supported for 'native' and 'stdio' protocols
-```
-
-**Solution**: Events currently work for `native` and `stdio` protocols only. Broker protocol event support is planned for future releases.
 
 ### Debug Mode
 
@@ -1214,22 +1200,13 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-## 📄 License
 
-MIT License - see [LICENSE](LICENSE) file for details
 
 ## 🔗 Related Projects
 
 - [@kadi.build/cli](https://gitlab.com/humin-game-lab/kadi/kadi) - Command-line interface
 - [@kadi.build/broker](https://gitlab.com/humin-game-lab/kadi/kadi-broker) - The KADI broker
 
-## 📚 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)
-
 ---
 
 Built with ❤️ by the KADI team