@koi-language/koi 1.0.0

package/src/runtime/router.js

@@ -0,0 +1,395 @@
+/**
+ * Agent Router with Intelligent Semantic Matching
+ *
+ * Uses a hybrid approach:
+ * 1. Fast embedding-based similarity search for initial filtering
+ * 2. LLM-based disambiguation when needed
+ *
+ * This allows agents to automatically discover and route tasks to the
+ * appropriate agent based on semantic understanding of capabilities.
+ */
+
+import { LLMProvider } from './llm-provider.js';
+import { cliLogger } from './cli-logger.js';
+
+export class AgentRouter {
+  constructor(config = {}) {
+    this.agents = new Map(); // Map<agentName, agent>
+    this.affordanceEmbeddings = []; // Array of { agent, event, description, embedding, confidence }
+    this.embeddingProvider = null;
+    this.llmProvider = null;
+
+    // Configuration
+    this.similarityThreshold = config.similarityThreshold || 0.4;  // Balanced threshold for semantic matching
+    this.highConfidenceThreshold = config.highConfidenceThreshold || 0.85;
+    this.useLLMDisambiguation = config.useLLMDisambiguation !== false;
+    this.cacheEmbeddings = config.cacheEmbeddings !== false;
+    this.verbose = config.verbose || false;
+  }
+
+  /**
+   * Register an agent and extract its affordances
+   * @param agent - The agent to register
+   * @param cachedAffordances - Optional pre-computed affordances from build cache
+   */
+  async register(agent, cachedAffordances = null) {
+    if (!agent || !agent.name) {
+      return;
+    }
+
+    this.agents.set(agent.name, agent);
+
+    // Use cached affordances if available
+    if (cachedAffordances) {
+      for (const [eventName, aff] of Object.entries(cachedAffordances)) {
+        if (!aff.embedding) {
+          // Fallback: generate at runtime if cache is incomplete
+          if (aff.description && aff.description.trim() !== '') {
+            aff.embedding = await this.getEmbedding(aff.description);
+          } else {
+            console.warn(`⚠️  [Router] Skipping ${agent.name}.${eventName} - empty description`);
+            continue;
+          }
+        }
+
+        this.affordanceEmbeddings.push({
+          agent: agent,
+          event: eventName,
+          description: aff.description,
+          embedding: aff.embedding,
+          confidence: aff.confidence,
+          metadata: { hasPlaybook: aff.hasPlaybook }
+        });
+      }
+
+      return;
+    }
+
+    // No cache: extract and generate affordances at runtime
+    const affordances = this.extractAffordances(agent);
+
+    // Generate embeddings for each affordance
+    for (const aff of affordances) {
+      if (!aff.description || aff.description.trim() === '') {
+        console.warn(`⚠️  [Router] Skipping ${agent.name}.${aff.event} - empty description`);
+        continue;
+      }
+
+      const embedding = await this.getEmbedding(aff.description);
+
+      this.affordanceEmbeddings.push({
+        agent: agent,
+        event: aff.event,
+        description: aff.description,
+        embedding: embedding,
+        confidence: aff.confidence,
+        metadata: aff.metadata
+      });
+    }
+  }
+
+  /**
+   * Extract affordances from an agent by analyzing its handlers and playbooks
+   */
+  extractAffordances(agent) {
+    const affordances = [];
+
+    if (!agent.handlers) {
+      return affordances;
+    }
+
+    for (const [eventName, handler] of Object.entries(agent.handlers)) {
+      // Try to infer description from playbook
+      const playbook = agent.playbooks?.[eventName];
+
+      let description;
+      let confidence;
+
+      if (playbook) {
+        description = this.inferIntentFromPlaybook(playbook, eventName);
+        confidence = 0.9; // High confidence when we have playbook
+      } else {
+        description = `Handle ${eventName} event`;
+        confidence = 0.5; // Lower confidence without playbook
+      }
+
+      affordances.push({
+        event: eventName,
+        description: description,
+        confidence: confidence,
+        metadata: {
+          hasPlaybook: !!playbook,
+          role: agent.role?.name
+        }
+      });
+    }
+
+    return affordances;
+  }
+
+  /**
+   * Infer the intent/capability from a playbook text
+   */
+  inferIntentFromPlaybook(playbook, eventName) {
+    // Remove template literals and get clean text
+    const cleanText = playbook
+      .replace(/\$\{[^}]+\}/g, '') // Remove ${...}
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0 && !line.startsWith('//'))
+      .slice(0, 3) // Take first 3 meaningful lines
+      .join(' ');
+
+    // If we got something meaningful, use it
+    if (cleanText.length > 10 && cleanText.length < 200) {
+      return cleanText;
+    }
+
+    // Fallback to event name processing
+    return this.humanizeEventName(eventName);
+  }
+
+  /**
+   * Convert camelCase/snake_case event names to readable descriptions
+   */
+  humanizeEventName(eventName) {
+    return eventName
+      .replace(/([A-Z])/g, ' $1') // camelCase
+      .replace(/_/g, ' ') // snake_case
+      .toLowerCase()
+      .trim();
+  }
+
+  /**
+   * Get embedding for text (with caching)
+   */
+  async getEmbedding(text) {
+    if (!this.embeddingProvider) {
+      this.embeddingProvider = new LLMProvider({
+        provider: 'openai',
+        model: 'text-embedding-3-small'
+      });
+    }
+
+    return await this.embeddingProvider.getEmbedding(text);
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   */
+  cosineSimilarity(vecA, vecB) {
+    if (!vecA || !vecB || vecA.length !== vecB.length) {
+      return 0;
+    }
+
+    const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
+    const magnitudeA = Math.sqrt(vecA.reduce((sum, a) => sum + a * a, 0));
+    const magnitudeB = Math.sqrt(vecB.reduce((sum, b) => sum + b * b, 0));
+
+    if (magnitudeA === 0 || magnitudeB === 0) {
+      return 0;
+    }
+
+    return dotProduct / (magnitudeA * magnitudeB);
+  }
+
+  /**
+   * Find matching agents using hybrid approach (embeddings + optional LLM)
+   */
+  async findMatches(intent, topK = 3) {
+    if (this.affordanceEmbeddings.length === 0) {
+      return [];
+    }
+
+    // Validate intent
+    if (!intent || typeof intent !== 'string' || intent.trim() === '') {
+      return [];
+    }
+
+    // Phase 1: Embedding-based similarity search
+    const intentEmbedding = await this.getEmbedding(intent);
+
+    const similarities = this.affordanceEmbeddings.map(aff => ({
+      ...aff,
+      similarity: this.cosineSimilarity(intentEmbedding, aff.embedding)
+    }));
+
+    // Sort by similarity descending
+    similarities.sort((a, b) => b.similarity - a.similarity);
+
+    // Filter by threshold
+    const candidates = similarities
+      .filter(s => s.similarity >= this.similarityThreshold)
+      .slice(0, Math.max(topK, 5)); // Get at least top 5 for LLM phase
+
+    if (candidates.length === 0) {
+      return [];
+    }
+
+    // Phase 2: High confidence early exit
+    if (candidates[0].similarity >= this.highConfidenceThreshold) {
+      return [candidates[0]];
+    }
+
+    // Phase 3: LLM disambiguation if multiple similar candidates
+    if (this.useLLMDisambiguation && candidates.length > 1) {
+      const topCandidates = candidates.slice(0, topK);
+
+      // Check if top candidates are close in similarity (ambiguous)
+      const similarityRange = topCandidates[0].similarity - topCandidates[topCandidates.length - 1].similarity;
+
+      if (similarityRange < 0.15) { // Within 15% similarity - ambiguous
+        return await this.disambiguateWithLLM(intent, topCandidates);
+      }
+    }
+
+    // Return top candidate
+    return [candidates[0]];
+  }
+
+  /**
+   * Use LLM to disambiguate between similar candidates
+   */
+  async disambiguateWithLLM(intent, candidates) {
+    if (!this.llmProvider) {
+      this.llmProvider = new LLMProvider({
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        temperature: 0.1,
+        max_tokens: 300
+      });
+    }
+
+    const candidateDescriptions = candidates.map((c, idx) => ({
+      id: idx,
+      agent: c.agent.name,
+      event: c.event,
+      description: c.description,
+      similarity: (c.similarity * 100).toFixed(1) + '%',
+      role: c.metadata?.role
+    }));
+
+    const prompt = `You are a task router. Select the BEST agent to handle this specific task.
+
+Task intent: "${intent}"
+
+Available agents (pre-filtered by semantic similarity):
+${JSON.stringify(candidateDescriptions, null, 2)}
+
+Which agent is the BEST match? Consider:
+- Semantic meaning and nuances of the task
+- Agent descriptions and capabilities
+- Task-specific requirements
+
+Return ONLY valid JSON (no markdown):
+{
+  "best_match_id": <id from 0 to ${candidates.length - 1}>,
+  "confidence": <number 0-1>,
+  "reasoning": "brief 1-sentence explanation"
+}`;
+
+    try {
+      const result = await this.llmProvider.executePlaybook(prompt, {});
+
+      if (typeof result.best_match_id === 'number' && result.best_match_id >= 0 && result.best_match_id < candidates.length) {
+        const selected = candidates[result.best_match_id];
+
+        return [{
+          ...selected,
+          similarity: result.confidence,
+          reasoning: result.reasoning,
+          llmDisambiguated: true
+        }];
+      } else {
+        return [candidates[0]];
+      }
+    } catch (error) {
+      return [candidates[0]];
+    }
+  }
+
+  /**
+   * Check if any agent can handle this intent
+   */
+  async canHandle(intent) {
+    const matches = await this.findMatches(intent, 1);
+    return matches.length > 0;
+  }
+
+  /**
+   * Get list of agents that can handle this intent
+   */
+  async whoCanHandle(intent, topK = 3) {
+    const matches = await this.findMatches(intent, topK);
+    return matches.map(m => ({
+      agent: m.agent.name,
+      event: m.event,
+      description: m.description,
+      similarity: m.similarity,
+      confidence: m.confidence,
+      reasoning: m.reasoning
+    }));
+  }
+
+  /**
+   * Route a task to the best matching agent
+   */
+  async route(task) {
+    const intent = task.intent || task.description || task.type;
+
+    if (!intent) {
+      throw new Error('[Router] Task must have an intent, description, or type');
+    }
+
+    const matches = await this.findMatches(intent, 1);
+
+    if (matches.length === 0) {
+      throw new Error(`[Router] No agent can handle: "${intent}"`);
+    }
+
+    const best = matches[0];
+
+    // Execute the task on the selected agent
+    return await best.agent.handle(best.event, task.data || {});
+  }
+
+  /**
+   * Get summary of registered agents and their capabilities
+   */
+  getSummary() {
+    const agentSummaries = [];
+
+    for (const [name, agent] of this.agents) {
+      const affordances = this.affordanceEmbeddings
+        .filter(aff => aff.agent === agent)
+        .map(aff => ({
+          event: aff.event,
+          description: aff.description,
+          confidence: aff.confidence
+        }));
+
+      agentSummaries.push({
+        name: name,
+        role: agent.role?.name,
+        affordances: affordances
+      });
+    }
+
+    return {
+      totalAgents: this.agents.size,
+      totalAffordances: this.affordanceEmbeddings.length,
+      agents: agentSummaries
+    };
+  }
+
+  /**
+   * Clear all registered agents (useful for testing)
+   */
+  clear() {
+    this.agents.clear();
+    this.affordanceEmbeddings = [];
+  }
+}
+
+// Singleton instance for global use
+export const agentRouter = new AgentRouter();

package/src/runtime/runtime.js

@@ -0,0 +1,113 @@
+import { agentRouter } from './router.js';
+import { cliLogger } from './cli-logger.js';
+
+export class Runtime {
+  static async send(config) {
+    const { base, filters = [], args = {}, timeout = 30000 } = config;
+
+    // Validate that base (team/peers) is not null
+    if (!base || base === null || base === undefined) {
+      const eventName = filters.find(f => f.type === 'event')?.name || 'unknown event';
+      throw new Error(`NO_AGENT_HANDLER:${eventName}::no-team`);
+    }
+
+    // Apply timeout
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => reject(new Error(`Timeout after ${timeout}ms`)), timeout);
+    });
+
+    try {
+      // Build query from filters
+      let query = base;
+
+      for (const filter of filters) {
+        if (filter.type === 'event') {
+          query = query.event(filter.name);
+        } else if (filter.type === 'role') {
+          query = query.role(filter.role);
+        } else if (filter.type === 'select') {
+          query = filter.mode === 'any' ? query.any() : query.all();
+        }
+      }
+
+      // Execute with timeout
+      const result = await Promise.race([
+        query.execute(args),
+        timeoutPromise
+      ]);
+
+      cliLogger.clear();
+      return result;
+    } catch (error) {
+      // Handle NO_AGENT_HANDLER errors specially
+      if (error.message && error.message.startsWith('NO_AGENT_HANDLER:')) {
+        const parts = error.message.split(':');
+        const eventName = parts[1] || 'unknown';
+        const roleInfo = parts[2] || '';
+        const teamName = parts[3] || '';
+
+        if (teamName === 'no-team') {
+          console.error(`\n❌ No agent available to handle event "${eventName}" - no team configured\n`);
+        } else {
+          const roleMsg = roleInfo ? ` (role: ${roleInfo})` : '';
+          console.error(`\n❌ No agent available to handle event "${eventName}"${roleMsg}\n`);
+        }
+        process.exit(1);
+      }
+
+      console.error('[Runtime] Send failed:', error.message);
+      throw error;
+    }
+  }
+
+  /**
+   * Create an agent and auto-register it with the router
+   */
+  static async createAgent(AgentClass, config) {
+    const agent = new AgentClass(config);
+
+    // Auto-register with router for dynamic discovery
+    if (agent.handlers && Object.keys(agent.handlers).length > 0) {
+      await agentRouter.register(agent);
+    }
+
+    return agent;
+  }
+
+  /**
+   * Create a team and auto-register all member agents
+   */
+  static async createTeam(TeamClass, name, members) {
+    const team = new TeamClass(name, members);
+
+    // Register all members with the router
+    for (const [memberName, agent] of Object.entries(members)) {
+      if (agent.handlers && Object.keys(agent.handlers).length > 0) {
+        await agentRouter.register(agent);
+      }
+    }
+
+    return team;
+  }
+
+  /**
+   * Register an existing agent with the router
+   */
+  static async registerAgent(agent) {
+    if (agent.handlers && Object.keys(agent.handlers).length > 0) {
+      await agentRouter.register(agent);
+    }
+  }
+
+  /**
+   * Get router summary for debugging
+   */
+  static getRouterSummary() {
+    return agentRouter.getSummary();
+  }
+
+  static log(message, level = 'info') {
+    const timestamp = new Date().toISOString();
+    console.log(`[${timestamp}] [${level.toUpperCase()}] ${message}`);
+  }
+}

package/src/runtime/skill-selector.js

@@ -0,0 +1,173 @@
+/**
+ * Skill Selector with Semantic Matching
+ *
+ * Uses embedding-based similarity search to intelligently select
+ * which skills are relevant for a given task, reducing the number
+ * of tools passed to the LLM and improving accuracy.
+ *
+ * Similar approach to AgentRouter but for skill selection.
+ */
+
+import { LLMProvider } from './llm-provider.js';
+
+export class SkillSelector {
+  constructor(config = {}) {
+    this.skillAffordances = []; // Array of { skillName, description, embedding, confidence, functions }
+    this.embeddingProvider = null;
+
+    // Configuration
+    this.similarityThreshold = config.similarityThreshold || 0.35; // Lower threshold for skills
+    this.verbose = config.verbose || false;
+  }
+
+  /**
+   * Register a skill with its affordance and available functions
+   * @param skillName - Name of the skill
+   * @param functions - Array of function objects { name, fn, description }
+   * @param cachedAffordance - Optional pre-computed affordance from build cache
+   */
+  async register(skillName, functions, cachedAffordance = null) {
+    if (!skillName || !functions || functions.length === 0) {
+      return;
+    }
+
+    let description, embedding, confidence;
+
+    // Use cached affordance if available
+    if (cachedAffordance) {
+      description = cachedAffordance.description;
+      embedding = cachedAffordance.embedding;
+      confidence = cachedAffordance.confidence || 0.9;
+
+      // Generate embedding at runtime if cache is incomplete
+      if (!embedding) {
+        if (description && description.trim() !== '') {
+          embedding = await this.getEmbedding(description);
+        } else {
+          console.warn(`⚠️  [SkillSelector] Skipping skill ${skillName} - empty description`);
+          return;
+        }
+      }
+    } else {
+      // No cache: use function descriptions as affordance
+      description = functions.map(f => f.description).join('. ');
+      if (!description || description.trim() === '') {
+        console.warn(`⚠️  [SkillSelector] Skipping skill ${skillName} - no function descriptions`);
+        return;
+      }
+      embedding = await this.getEmbedding(description);
+      confidence = 0.7;
+    }
+
+    this.skillAffordances.push({
+      skillName,
+      description,
+      embedding,
+      confidence,
+      functions
+    });
+  }
+
+  /**
+   * Select relevant skills for a given task/playbook using semantic matching
+   * @param playbookContent - The playbook text describing what needs to be done
+   * @param maxSkills - Maximum number of skills to return
+   * @returns Array of function objects to pass to LLM
+   */
+  async selectSkillsForTask(playbookContent, maxSkills = 2) {
+    if (this.skillAffordances.length === 0) {
+      return [];
+    }
+
+    // If playbook is too short or generic, return all skills
+    if (!playbookContent || playbookContent.trim().length < 20) {
+      // Return all available functions from all skills
+      return this.skillAffordances.flatMap(skill => skill.functions);
+    }
+
+    // Extract the meaningful part of the playbook (first few sentences)
+    const intent = this.extractIntent(playbookContent);
+
+    // Generate embedding for the task intent
+    const intentEmbedding = await this.getEmbedding(intent);
+
+    // Calculate similarity with each skill
+    const similarities = this.skillAffordances.map(skill => ({
+      ...skill,
+      similarity: this.cosineSimilarity(intentEmbedding, skill.embedding)
+    }));
+
+    // Sort by similarity descending
+    similarities.sort((a, b) => b.similarity - a.similarity);
+
+    // Filter by threshold and take top N
+    const relevantSkills = similarities
+      .filter(s => s.similarity >= this.similarityThreshold)
+      .slice(0, maxSkills);
+
+    if (this.verbose && relevantSkills.length > 0) {
+      console.log(`[SkillSelector] Selected ${relevantSkills.length} skills for: "${intent.substring(0, 50)}..."`);
+      relevantSkills.forEach(skill => {
+        console.log(`  - ${skill.skillName} (similarity: ${skill.similarity.toFixed(3)})`);
+      });
+    }
+
+    // Return functions from relevant skills
+    return relevantSkills.flatMap(skill => skill.functions);
+  }
+
+  /**
+   * Extract intent from playbook content
+   */
+  extractIntent(playbookContent) {
+    // Remove template literals and extract meaningful sentences
+    const cleanText = playbookContent
+      .replace(/\$\{[^}]+\}/g, '') // Remove ${...}
+      .replace(/IMPORTANT:.*/gi, '') // Remove "IMPORTANT" instructions
+      .replace(/Return.*JSON.*/gi, '') // Remove JSON format instructions
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line.length > 0 && !line.startsWith('//'))
+      .slice(0, 3) // Take first 3 meaningful lines
+      .join(' ')
+      .trim();
+
+    return cleanText || playbookContent.substring(0, 200);
+  }
+
+  /**
+   * Get embedding for text (with lazy initialization)
+   */
+  async getEmbedding(text) {
+    if (!this.embeddingProvider) {
+      this.embeddingProvider = new LLMProvider({
+        provider: 'openai',
+        model: 'text-embedding-3-small'
+      });
+    }
+
+    return await this.embeddingProvider.getEmbedding(text);
+  }
+
+  /**
+   * Calculate cosine similarity between two vectors
+   */
+  cosineSimilarity(vecA, vecB) {
+    if (!vecA || !vecB || vecA.length !== vecB.length) {
+      return 0;
+    }
+
+    const dotProduct = vecA.reduce((sum, a, i) => sum + a * vecB[i], 0);
+    const magnitudeA = Math.sqrt(vecA.reduce((sum, a) => sum + a * a, 0));
+    const magnitudeB = Math.sqrt(vecB.reduce((sum, b) => sum + b * b, 0));
+
+    if (magnitudeA === 0 || magnitudeB === 0) {
+      return 0;
+    }
+
+    return dotProduct / (magnitudeA * magnitudeB);
+  }
+}
+
+// Global skill selector instance
+export const skillSelector = new SkillSelector({ verbose: false });

package/src/runtime/skill.js

@@ -0,0 +1,25 @@
+export class Skill {
+  constructor(config) {
+    this.name = config.name;
+    this.affordance = config.affordance || '';
+    this.run = config.run || (async () => ({ error: 'Not implemented' }));
+    this.agents = config.agents || {};
+  }
+
+  async execute(input) {
+    console.log(`[Skill:${this.name}] Executing with input:`, input);
+
+    try {
+      const result = await this.run(input);
+      console.log(`[Skill:${this.name}] Completed successfully`);
+      return result;
+    } catch (error) {
+      console.error(`[Skill:${this.name}] Error:`, error.message);
+      return { error: error.message };
+    }
+  }
+
+  toString() {
+    return `Skill(${this.name})`;
+  }
+}