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

package/examples/example-abilities/echo-js/README.md

@@ -1,131 +0,0 @@
-# Echo-JS Ability
-
-A simple echo ability that demonstrates the new **improved KadiAbility architecture**. This ability showcases how easy it is to create powerful abilities with minimal code.
-
-## What This Demonstrates
-
-### 🏗️ **New Architecture Benefits**
-
-1. **Cleaner Code**: The entire ability is ~100 lines vs ~600+ lines with the old architecture
-2. **Transport Abstraction**: Automatically works with stdio and broker modes
-3. **Built-in Discovery**: `__kadi_init` and `__kadi_discover` methods are automatic
-4. **Better Error Handling**: Protocol errors are handled gracefully
-5. **Metadata Support**: Easy to add schemas and descriptions to methods
-
-### 🚀 **Simple API**
-
-```javascript
-const ability = new KadiAbility({ name: 'echo-js' });
-
-ability
-  .method('echo', async ({ message }) => {
-    return { echo: message, timestamp: new Date().toISOString() };
-  })
-  .serve();
-```
-
-That's it! The new architecture handles:
-
-- LSP framing for stdio communication
-- Request/response correlation
-- Error handling
-- Discovery methods
-- Transport selection
-
-## Available Methods
-
-### `echo`
-
-Returns your message with metadata:
-
-```json
-{
-  "method": "echo",
-  "params": { "message": "Hello!" }
-}
-// Returns: { "echo": "Hello!", "timestamp": "2024-...", "length": 6 }
-```
-
-### `mirror`
-
-Returns your entire input object:
-
-```json
-{
-  "method": "mirror",
-  "params": { "foo": "bar", "numbers": [1, 2, 3] }
-}
-// Returns: { "mirrored": {...}, "metadata": {...} }
-```
-
-### `health`
-
-Returns service health status:
-
-```json
-{
-  "method": "health",
-  "params": {}
-}
-// Returns: { "status": "healthy", "uptime": 12345, "version": "0.0.1" }
-```
-
-## Running
-
-### Stdio Mode (default)
-
-```bash
-node service.js
-# Then send JSON-RPC messages via stdin
-```
-
-### Broker Mode
-
-```bash
-KADI_MODE=broker KADI_BROKER_URL=ws://localhost:8080 node service.js
-```
-
-### Testing
-
-```bash
-node test-manual.js
-```
-
-## Architecture Comparison
-
-### Before (Old KadiAbility)
-
-```javascript
-// Had to implement:
-// - LSP frame reading/writing (~200 lines)
-// - Request/response loop (~100 lines)
-// - Error handling (~100 lines)
-// - Discovery methods (~50 lines)
-// - Transport management (~50 lines)
-// Total: ~500+ lines before any business logic!
-```
-
-### After (New Architecture)
-
-```javascript
-import { KadiAbility } from '@kadi/core';
-
-const ability = new KadiAbility({ name: 'my-ability' });
-ability.method('myMethod', handler);
-ability.serve();
-
-// Everything else is handled automatically!
-// Focus on business logic, not plumbing.
-```
-
-## Key Features Demonstrated
-
-- ✅ **Multiple Methods**: echo, mirror, health
-- ✅ **Method Metadata**: Descriptions and schemas
-- ✅ **Error Handling**: Graceful error responses
-- ✅ **Event Monitoring**: Request/response logging
-- ✅ **Discovery**: Built-in `__kadi_init` and `__kadi_discover`
-- ✅ **Transport Agnostic**: Works with stdio and broker modes
-- ✅ **Clean Shutdown**: Handles SIGINT/SIGTERM
-
-This is what ability development should feel like! 🎉

package/examples/example-abilities/echo-js/agent.json

@@ -1,63 +0,0 @@
-{
-  "name": "echo-js",
-  "kind": "ability",
-  "version": "0.0.1",
-  "license": "MIT",
-  "description": "Simple echo ability that returns whatever you send to it - demonstrates the new KadiAbility architecture.",
-  "repo": "",
-  "brokers": {
-    "local": "ws://127.0.0.1:8080",
-    "remote": "ws://kadi.build:8080"
-  },
-  "abilities": {},
-  "scripts": {
-    "preflight": "npm uninstall @kadi.build/core && npm cache clean --force && npm pack ../../../../../ && npm install kadi.build-core-0.0.1-alpha.2.tgz && rm kadi.build-core-0.0.1-alpha.2.tgz",
-    "setup": "npm install",
-    "start": "node service.js",
-    "stop": ""
-  },
-  "interfaces": {
-    "native": {
-      "entry": "service.js"
-    },
-    "stdio": {
-      "discover": true,
-      "timeoutMs": 10000
-    },
-    "broker": {
-      "discover": true,
-      "timeoutMs": 15000
-    }
-  },
-  "exports": [
-    {
-      "name": "echo",
-      "title": "Echo",
-      "description": "Returns the exact input you provide - useful for testing.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "message": {
-            "type": "string",
-            "description": "Message to echo back"
-          }
-        },
-        "required": ["message"]
-      },
-      "outputSchema": {
-        "type": "object",
-        "properties": {
-          "echo": {
-            "type": "string"
-          },
-          "timestamp": {
-            "type": "string"
-          },
-          "length": {
-            "type": "number"
-          }
-        }
-      }
-    }
-  ]
-}

package/examples/example-abilities/echo-js/package.json

@@ -1,24 +0,0 @@
-{
-  "name": "echo-js",
-  "version": "0.0.1",
-  "description": "Simple echo ability demonstrating the new KadiAbility architecture",
-  "type": "module",
-  "main": "service.js",
-  "scripts": {
-    "preflight": "",
-    "setup": "npm install",
-    "start": "node service.js",
-    "test": "echo 'No tests yet'"
-  },
-  "keywords": [
-    "kadi",
-    "ability",
-    "echo",
-    "demo"
-  ],
-  "author": "",
-  "license": "MIT",
-  "dependencies": {
-    "@kadi.build/core": "file:../../../../../Repositories/KADI/kadi-core/kadi.build-core-0.0.1-alpha.2.tgz"
-  }
-}

package/examples/example-abilities/echo-js/service.js

@@ -1,43 +0,0 @@
-// echo-js/index.ts (or .js)
-import { KadiAbility } from '@kadi.build/core';
-
-const echoAbility = new KadiAbility({
-  name: 'echo-js',
-  version: '0.0.1',
-  description:
-    'Simple echo ability demonstrating the new KadiAbility architecture',
-  scope: process.env.KADI_AGENT_SCOPE
-});
-
-async function echo(message) {
-  const timestamp = new Date().toISOString();
-  const messageText = message?.message ?? message ?? '';
-  const length = messageText.length;
-
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo' });
-  echoAbility.publishEvent('echo:test-event', { from: 'message echo 2' });
-
-  return { echo: messageText, timestamp, length };
-}
-
-async function say_message(message) {
-  return { message };
-}
-
-// Register 'echo' and 'say_message' methods
-echoAbility.method('echo', echo);
-
-echoAbility.method('say_message', say_message, {
-  description: 'Say a message',
-  inputSchema: { type: 'object', properties: { message: { type: 'string' } } },
-  outputSchema: { type: 'object', properties: { message: { type: 'string' } } }
-});
-
-// For native/in-process you usually do NOT need serve().
-// If you keep it for other protocols, it won’t hurt, but isn’t required here.
-echoAbility.serve().catch((error) => {
-  console.error(`[echo-js] Fatal error: ${error.message}`);
-  process.exit(1);
-});
-
-export default echoAbility;

package/examples/example-abilities/hash-go/agent.json

@@ -1,53 +0,0 @@
-{
-  "name": "hash-go",
-  "kind": "ability",
-  "version": "0.0.1",
-  "license": "MIT",
-  "description": "Compute digests (sha256 default).",
-  "repo": "",
-  "brokers": {
-    "local": "ws://127.0.0.1:8080",
-    "remote": "ws://146.190.121.213:8080"
-  },
-  "abilities": {},
-  "scripts": {
-    "preflight": "",
-    "setup": "go mod tidy && mkdir -p bin && go build -o bin/hash_ability ./cmd/hash_ability",
-    "start": "./bin/hash_ability",
-    "stop": ""
-  },
-  "interfaces": {
-    "stdio": {
-      "discover": true,
-      "timeoutMs": 10000
-    }
-  },
-  "exports": [
-    {
-      "name": "digest",
-      "title": "Compute Digest",
-      "description": "Return a hex digest of the input text.",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "text": { "type": "string", "description": "Input text" },
-          "algo": {
-            "type": "string",
-            "enum": ["sha256", "md5"],
-            "default": "sha256",
-            "description": "Hash algorithm"
-          }
-        },
-        "required": ["text"]
-      },
-      "outputSchema": {
-        "type": "object",
-        "properties": {
-          "algo": { "type": "string" },
-          "hex": { "type": "string" }
-        },
-        "required": ["algo", "hex"]
-      }
-    }
-  ]
-}

package/examples/example-abilities/hash-go/cmd/hash_ability/main.go

@@ -1,340 +0,0 @@
-// A minimal JSON-RPC 2.0 server over stdin/stdout for the "hash-go" ability.
-// - Uses LSP-style framing: Kadi-Content-Length header + JSON body
-// - Implements:
-//     __kadi_init       : handshake/version negotiation
-//     __kadi_discover   : returns functions/tools metadata
-//     digest            : computes sha256/md5 hex digest of input text
-//
-// This follows the LSP-style protocol used by spawnJSONRPCProcess() in kadi-core.
-
-package main
-
-import (
-	"crypto/md5"
-	"crypto/sha256"
-	"encoding/hex"
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-	"strconv"
-	"strings"
-)
-
-// RPCRequest models a JSON-RPC request coming from the agent.
-// ID is left as interface{} so we can echo back either number or string.
-type RPCRequest struct {
-	JSONRPC string          `json:"jsonrpc"`
-	ID      interface{}     `json:"id"`
-	Method  string          `json:"method"`
-	Params  json.RawMessage `json:"params"`
-}
-
-// RPCError is the error object defined by JSON-RPC 2.0.
-type RPCError struct {
-	Code    int    `json:"code"`
-	Message string `json:"message"`
-}
-
-// RPCResponse models a JSON-RPC response. Either Result or Error is present.
-type RPCResponse struct {
-	JSONRPC string      `json:"jsonrpc"`
-	ID      interface{} `json:"id"`
-	Result  interface{} `json:"result,omitempty"`
-	Error   *RPCError   `json:"error,omitempty"`
-}
-
-// digestParams describes the input we expect for the "digest" method/tool.
-type digestParams struct {
-	Text string `json:"text"`
-	Algo string `json:"algo"` // "sha256" (default) or "md5"
-}
-
-// toolSpec models an MCP-style tool descriptor.
-type toolSpec struct {
-	Name         string                 `json:"name"`
-	Title        string                 `json:"title,omitempty"`
-	Description  string                 `json:"description,omitempty"`
-	InputSchema  map[string]interface{} `json:"inputSchema"`
-	OutputSchema map[string]interface{} `json:"outputSchema,omitempty"`
-}
-
-func main() {
-	// Loop forever: read LSP-style frames → handle → write response.
-	for {
-		// Read headers byte by byte until we find \r\n\r\n
-		headers := make(map[string]string)
-		headerData := make([]byte, 0)
-
-		// Read until we find the header delimiter \r\n\r\n
-		delimiter := []byte{'\r', '\n', '\r', '\n'}
-		for {
-			b := make([]byte, 1)
-			_, err := os.Stdin.Read(b)
-			if err != nil {
-				if err == io.EOF {
-					return // Clean exit
-				}
-				fmt.Fprintf(os.Stderr, "Error reading header byte: %v\n", err)
-				return
-			}
-			headerData = append(headerData, b[0])
-
-			// Check if we have the delimiter
-			if len(headerData) >= 4 {
-				if string(headerData[len(headerData)-4:]) == string(delimiter) {
-					break
-				}
-			}
-		}
-
-		// Parse headers (exclude the delimiter)
-		headerSection := string(headerData[:len(headerData)-4])
-		lines := strings.Split(headerSection, "\r\n")
-
-		for _, line := range lines {
-			if strings.Contains(line, ":") {
-				parts := strings.SplitN(line, ":", 2)
-				if len(parts) == 2 {
-					name := strings.TrimSpace(parts[0])
-					value := strings.TrimSpace(parts[1])
-					headers[name] = value
-				}
-			}
-		}
-
-		// Extract Content-Length
-		contentLengthStr, ok := headers["Kadi-Content-Length"]
-		if !ok {
-			fmt.Fprintf(os.Stderr, "Missing Content-Length header\n")
-			continue
-		}
-
-		contentLength, err := strconv.Atoi(contentLengthStr)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "Invalid Content-Length: %v\n", err)
-			continue
-		}
-
-		// Read the JSON body
-		body := make([]byte, contentLength)
-		_, err = io.ReadFull(os.Stdin, body)
-		if err != nil {
-			fmt.Fprintf(os.Stderr, "Error reading body: %v\n", err)
-			continue
-		}
-
-		var req RPCRequest
-		if err := json.Unmarshal(body, &req); err != nil {
-			// If the request can't be parsed, return a JSON-RPC parse error (-32700).
-			writeResponse(RPCResponse{
-				JSONRPC: "2.0",
-				ID:      nil,
-				Error:   &RPCError{Code: -32700, Message: "parse error: " + err.Error()},
-			})
-			continue
-		}
-
-		// Dispatch by method. Each handler returns (result, *RPCError).
-		var (
-			result interface{}
-			rerr   *RPCError
-		)
-
-		switch req.Method {
-		case "__kadi_init":
-			// Handshake/version negotiation. You can return metadata here.
-			result, rerr = handleInit(req.Params)
-
-		case "__kadi_discover":
-			// Return functions map + optional tools array (mirrors MCP).
-			result, rerr = handleDiscover()
-
-		case "digest":
-			// Direct method call (what loadAbility().call("digest", ...) would use).
-			result, rerr = handleDigest(req.Params)
-
-		default:
-			// Method not found (-32601) per JSON-RPC.
-			rerr = &RPCError{Code: -32601, Message: "method not found: " + req.Method}
-		}
-
-		// Send the response using LSP-style framing.
-		writeResponse(RPCResponse{
-			JSONRPC: "2.0",
-			ID:      req.ID,
-			Result:  result,
-			Error:   rerr,
-		})
-	}
-}
-
-// writeResponse serializes and prints a JSON-RPC response using LSP-style framing.
-// Format: Content-Length header + JSON body
-func writeResponse(resp RPCResponse) {
-	b, err := json.Marshal(resp)
-	if err != nil {
-		// As a last resort, emit a generic error with no ID.
-		fallback := RPCResponse{
-			JSONRPC: "2.0",
-			ID:      nil,
-			Error:   &RPCError{Code: -32603, Message: "internal error: " + err.Error()},
-		}
-		b, _ = json.Marshal(fallback)
-	}
-
-	// Write LSP-style frame: headers + body
-	header := fmt.Sprintf("Kadi-Content-Length: %d\r\nContent-Type: application/kadi-jsonrpc; charset=utf-8\r\n\r\n", len(b))
-	fmt.Print(header)
-	fmt.Print(string(b))
-}
-
-/* ----------------------------- Handlers ---------------------------------- */
-
-// handleInit replies to __kadi_init. You can extend this with capabilities.
-func handleInit(params json.RawMessage) (interface{}, *RPCError) {
-	// Optionally parse params to inspect the API version.
-	var payload map[string]interface{}
-	_ = json.Unmarshal(params, &payload)
-
-	// Return metadata; you could also include "functions" here to skip discover.
-	return map[string]interface{}{
-		"api": "1.0",
-		"ability": map[string]interface{}{
-			"name":    "hash-go",
-			"version": "0.0.1",
-		},
-	}, nil
-}
-
-// handleDiscover advertises callable functions (your loader can auto-stub from this).
-// We also include an MCP-compatible "tools" array for symmetry.
-func handleDiscover() (interface{}, *RPCError) {
-	input, output := digestSchemas()
-
-	return map[string]interface{}{
-		"functions": map[string]interface{}{
-			"digest": map[string]interface{}{
-				"inputSchema":  input,
-				"outputSchema": output,
-			},
-		},
-		"tools": []toolSpec{
-			{
-				Name:        "digest",
-				Title:       "Compute Digest",
-				Description: "Return a hex digest (sha256 default) of the input text.",
-				InputSchema: input,
-				OutputSchema: map[string]interface{}{
-					"type": "object",
-					"properties": map[string]interface{}{
-						"algo": map[string]interface{}{"type": "string"},
-						"hex":  map[string]interface{}{"type": "string"},
-					},
-					"required": []string{"algo", "hex"},
-				},
-			},
-		},
-	}, nil
-}
-
-// handleToolsList matches MCP "tools/list": return the list of tools.
-func handleToolsList() (interface{}, *RPCError) {
-	input, _ := digestSchemas()
-	tools := []toolSpec{
-		{
-			Name:        "digest",
-			Title:       "Compute Digest",
-			Description: "Return a hex digest (sha256 default) of the input text.",
-			InputSchema: input,
-			OutputSchema: map[string]interface{}{
-				"type": "object",
-				"properties": map[string]interface{}{
-					"algo": map[string]interface{}{"type": "string"},
-					"hex":  map[string]interface{}{"type": "string"},
-				},
-				"required": []string{"algo", "hex"},
-			},
-		},
-	}
-	return tools, nil
-}
-
-// handleToolsCall matches MCP "tools/call": expects {"name": "...", "arguments": {...}}
-func handleToolsCall(params json.RawMessage) (interface{}, *RPCError) {
-	var p struct {
-		Name      string          `json:"name"`
-		Arguments json.RawMessage `json:"arguments"`
-	}
-	if err := json.Unmarshal(params, &p); err != nil {
-		return nil, &RPCError{Code: -32602, Message: "invalid params: " + err.Error()}
-	}
-	switch p.Name {
-	case "digest":
-		// Reuse our regular digest handler for the arguments payload.
-		return handleDigest(p.Arguments)
-	default:
-		return nil, &RPCError{Code: -32601, Message: "tool not found: " + p.Name}
-	}
-}
-
-// handleDigest is the actual business logic: compute a digest and return algo+hex.
-func handleDigest(params json.RawMessage) (interface{}, *RPCError) {
-	var p digestParams
-	if err := json.Unmarshal(params, &p); err != nil {
-		return nil, &RPCError{Code: -32602, Message: "invalid params: " + err.Error()}
-	}
-	if p.Algo == "" {
-		p.Algo = "sha256"
-	}
-
-	textBytes := []byte(p.Text)
-	switch strings.ToLower(p.Algo) {
-	case "sha256":
-		sum := sha256.Sum256(textBytes)
-		return map[string]interface{}{
-			"algo": "sha256",
-			"hex":  hex.EncodeToString(sum[:]),
-		}, nil
-	case "md5":
-		sum := md5.Sum(textBytes)
-		return map[string]interface{}{
-			"algo": "md5",
-			"hex":  hex.EncodeToString(sum[:]),
-		}, nil
-	default:
-		return nil, &RPCError{Code: -32602, Message: "unsupported algo: " + p.Algo}
-	}
-}
-
-/* --------------------------- JSON Schemas -------------------------------- */
-
-// digestSchemas returns the JSON Schemas for input/output (as plain Go maps).
-func digestSchemas() (input map[string]interface{}, output map[string]interface{}) {
-	input = map[string]interface{}{
-		"type": "object",
-		"properties": map[string]interface{}{
-			"text": map[string]interface{}{
-				"type":        "string",
-				"description": "Input text to hash.",
-			},
-			"algo": map[string]interface{}{
-				"type":        "string",
-				"enum":        []interface{}{"sha256", "md5"},
-				"default":     "sha256",
-				"description": "Hash algorithm.",
-			},
-		},
-		"required": []string{"text"},
-	}
-
-	output = map[string]interface{}{
-		"type": "object",
-		"properties": map[string]interface{}{
-			"algo": map[string]interface{}{"type": "string"},
-			"hex":  map[string]interface{}{"type": "string"},
-		},
-		"required": []string{"algo", "hex"},
-	}
-	return
-}

package/examples/example-abilities/hash-go/go.mod

@@ -1,3 +0,0 @@
-module hash_ability
-
-go 1.21