signalwire-agents 0.1.0

package/src/skills/SkillManager.ts

@@ -0,0 +1,177 @@
+/**
+ * SkillManager - Manages skill lifecycle for an agent.
+ *
+ * Handles loading, unloading, validation, and injection of
+ * skill tools, hints, global data, and prompt sections.
+ */
+
+import { SkillBase } from './SkillBase.js';
+import { getLogger } from '../Logger.js';
+
+const log = getLogger('SkillManager');
+
+/**
+ * Manages the lifecycle of skills attached to an agent.
+ *
+ * Handles loading, unloading, validation, and aggregation of skill tools,
+ * hints, global data, and prompt sections.
+ */
+export class SkillManager {
+  private skills: Map<string, SkillBase> = new Map();
+
+  /**
+   * Add a skill to the manager, validating env vars and calling setup().
+   * @param skill - The skill instance to add.
+   */
+  async addSkill(skill: SkillBase): Promise<void> {
+    const name = skill.skillName;
+
+    if (this.skills.has(skill.instanceId)) {
+      throw new Error(`Skill instance '${skill.instanceId}' is already loaded`);
+    }
+
+    // Validate required env vars
+    const missingEnvVars = skill.validateEnvVars();
+    if (missingEnvVars.length) {
+      log.warn(`Skill '${name}' missing env vars: ${missingEnvVars.join(', ')}`);
+    }
+
+    // Setup
+    await skill.setup();
+    skill.markInitialized();
+
+    this.skills.set(skill.instanceId, skill);
+    log.debug(`Added skill '${name}' (${skill.instanceId})`);
+  }
+
+  /**
+   * Remove a skill by its instance ID, calling cleanup() before removal.
+   * @param instanceId - The unique instance ID of the skill to remove.
+   * @returns True if the skill was found and removed, false otherwise.
+   */
+  async removeSkill(instanceId: string): Promise<boolean> {
+    const skill = this.skills.get(instanceId);
+    if (!skill) return false;
+
+    await skill.cleanup();
+    this.skills.delete(instanceId);
+    log.debug(`Removed skill '${skill.skillName}' (${instanceId})`);
+    return true;
+  }
+
+  /**
+   * Remove all skill instances matching a given skill name.
+   * @param skillName - The skill name to match against.
+   * @returns The number of skill instances removed.
+   */
+  async removeSkillByName(skillName: string): Promise<number> {
+    let count = 0;
+    for (const [id, skill] of this.skills) {
+      if (skill.skillName === skillName) {
+        await skill.cleanup();
+        this.skills.delete(id);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Check if any skill instance with the given name is currently loaded.
+   * @param skillName - The skill name to check for.
+   * @returns True if at least one instance with this name is loaded.
+   */
+  hasSkill(skillName: string): boolean {
+    for (const skill of this.skills.values()) {
+      if (skill.skillName === skillName) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get a skill by its unique instance ID.
+   * @param instanceId - The instance ID to look up.
+   * @returns The skill instance, or undefined if not found.
+   */
+  getSkill(instanceId: string): SkillBase | undefined {
+    return this.skills.get(instanceId);
+  }
+
+  /**
+   * List all loaded skill instances with their name, ID, and initialization state.
+   * @returns Array of skill summary objects.
+   */
+  listSkills(): { name: string; instanceId: string; initialized: boolean }[] {
+    return Array.from(this.skills.values()).map(s => ({
+      name: s.skillName,
+      instanceId: s.instanceId,
+      initialized: s.isInitialized(),
+    }));
+  }
+
+  /**
+   * Aggregate tool definitions from all loaded skills.
+   * @returns Combined array of all skill tool definitions.
+   */
+  getAllTools(): ReturnType<SkillBase['getTools']> {
+    const tools: ReturnType<SkillBase['getTools']> = [];
+    for (const skill of this.skills.values()) {
+      tools.push(...skill.getTools());
+    }
+    return tools;
+  }
+
+  /**
+   * Aggregate prompt sections from all loaded skills.
+   * @returns Combined array of all skill prompt sections.
+   */
+  getAllPromptSections(): ReturnType<SkillBase['getPromptSections']> {
+    const sections: ReturnType<SkillBase['getPromptSections']> = [];
+    for (const skill of this.skills.values()) {
+      sections.push(...skill.getPromptSections());
+    }
+    return sections;
+  }
+
+  /**
+   * Aggregate speech recognition hints from all loaded skills.
+   * @returns Combined array of all skill hint strings.
+   */
+  getAllHints(): string[] {
+    const hints: string[] = [];
+    for (const skill of this.skills.values()) {
+      hints.push(...skill.getHints());
+    }
+    return hints;
+  }
+
+  /**
+   * Merge global data from all loaded skills into a single object.
+   * @returns Combined global data (later skills override earlier ones on key conflicts).
+   */
+  getMergedGlobalData(): Record<string, unknown> {
+    const data: Record<string, unknown> = {};
+    for (const skill of this.skills.values()) {
+      Object.assign(data, skill.getGlobalData());
+    }
+    return data;
+  }
+
+  /**
+   * Get the number of currently loaded skill instances.
+   * @returns The count of loaded skills.
+   */
+  get size(): number {
+    return this.skills.size;
+  }
+
+  /**
+   * Remove all skills and clean up.
+   */
+  async clear(): Promise<void> {
+    for (const skill of this.skills.values()) {
+      await skill.cleanup();
+    }
+    this.skills.clear();
+  }
+}

package/src/skills/SkillRegistry.ts

@@ -0,0 +1,231 @@
+/**
+ * SkillRegistry - Global singleton registry for discovering and loading skills.
+ *
+ * Skills can be registered programmatically or discovered from directories.
+ * Supports SIGNALWIRE_SKILL_PATHS env var for custom skill directories.
+ */
+
+import { SkillBase, type SkillConfig, type SkillManifest } from './SkillBase.js';
+import { getLogger } from '../Logger.js';
+
+const log = getLogger('SkillRegistry');
+
+/** Factory function that creates a SkillBase instance from optional configuration. */
+export type SkillFactory = (config?: SkillConfig) => SkillBase;
+
+/** Internal registry entry associating a skill name with its factory and optional manifest. */
+interface RegistryEntry {
+  /** Registered skill name. */
+  name: string;
+  /** Factory function to create instances of this skill. */
+  factory: SkillFactory;
+  /** Optional pre-loaded manifest for the skill. */
+  manifest?: SkillManifest;
+}
+
+let _instance: SkillRegistry | null = null;
+
+/**
+ * Global singleton registry for discovering and instantiating skills.
+ *
+ * Skills can be registered programmatically or auto-discovered from directories.
+ * Supports the SIGNALWIRE_SKILL_PATHS environment variable for custom skill directories.
+ */
+export class SkillRegistry {
+  private registry: Map<string, RegistryEntry> = new Map();
+  private searchPaths: string[];
+
+  constructor() {
+    const envPaths = process.env['SIGNALWIRE_SKILL_PATHS'];
+    this.searchPaths = envPaths ? envPaths.split(':').filter(Boolean) : [];
+  }
+
+  /**
+   * Get the global singleton instance, creating it on first access.
+   * @returns The shared SkillRegistry instance.
+   */
+  static getInstance(): SkillRegistry {
+    if (!_instance) {
+      _instance = new SkillRegistry();
+    }
+    return _instance;
+  }
+
+  /**
+   * Reset the global singleton (for testing).
+   */
+  static resetInstance(): void {
+    _instance = null;
+  }
+
+  /**
+   * Register a skill factory by name, optionally with a pre-loaded manifest.
+   * @param name - The unique skill name.
+   * @param factory - Factory function to create skill instances.
+   * @param manifest - Optional manifest metadata for the skill.
+   */
+  register(name: string, factory: SkillFactory, manifest?: SkillManifest): void {
+    if (this.registry.has(name)) {
+      log.warn(`Overwriting skill registration: ${name}`);
+    }
+    this.registry.set(name, { name, factory, manifest });
+    log.debug(`Registered skill: ${name}`);
+  }
+
+  /**
+   * Unregister a skill by name, removing it from the registry.
+   * @param name - The skill name to unregister.
+   * @returns True if the skill was found and removed.
+   */
+  unregister(name: string): boolean {
+    return this.registry.delete(name);
+  }
+
+  /**
+   * Create a new skill instance by looking up its factory in the registry.
+   * @param name - The registered skill name.
+   * @param config - Optional configuration to pass to the factory.
+   * @returns A new skill instance, or null if the name is not registered.
+   */
+  create(name: string, config?: SkillConfig): SkillBase | null {
+    const entry = this.registry.get(name);
+    if (!entry) {
+      log.warn(`Skill not found in registry: ${name}`);
+      return null;
+    }
+    return entry.factory(config);
+  }
+
+  /**
+   * Check if a skill name is registered.
+   * @param name - The skill name to check.
+   * @returns True if the skill is registered.
+   */
+  has(name: string): boolean {
+    return this.registry.has(name);
+  }
+
+  /**
+   * Get the manifest for a registered skill, if available.
+   * @param name - The skill name to look up.
+   * @returns The skill manifest, or undefined if not found or not provided.
+   */
+  getManifest(name: string): SkillManifest | undefined {
+    return this.registry.get(name)?.manifest;
+  }
+
+  /**
+   * List all registered skill names.
+   * @returns Array of registered skill name strings.
+   */
+  listRegistered(): string[] {
+    return Array.from(this.registry.keys());
+  }
+
+  /**
+   * List all registered skills with their optional manifests.
+   * @returns Array of objects containing skill name and manifest.
+   */
+  listRegisteredWithManifests(): { name: string; manifest?: SkillManifest }[] {
+    return Array.from(this.registry.values()).map(e => ({
+      name: e.name,
+      manifest: e.manifest,
+    }));
+  }
+
+  /**
+   * Add a directory path to search during skill discovery.
+   * @param path - Absolute path to a directory containing skill files.
+   */
+  addSearchPath(path: string): void {
+    if (!this.searchPaths.includes(path)) {
+      this.searchPaths.push(path);
+    }
+  }
+
+  /**
+   * Get all configured search paths for skill discovery.
+   * @returns Copy of the search paths array.
+   */
+  getSearchPaths(): string[] {
+    return [...this.searchPaths];
+  }
+
+  /**
+   * Discover and register skills from a directory by importing each file.
+   * Looks for modules exporting a `createSkill` factory or a SkillBase default export.
+   * @param dirPath - Absolute path to the directory to scan.
+   * @returns Array of newly discovered skill names.
+   */
+  async discoverFromDirectory(dirPath: string): Promise<string[]> {
+    const { readdir } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    const { pathToFileURL } = await import('node:url');
+
+    const discovered: string[] = [];
+    let entries: string[];
+
+    try {
+      const dirEntries = await readdir(dirPath, { withFileTypes: true });
+      entries = dirEntries
+        .filter(e => (e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.js'))) || e.isDirectory())
+        .map(e => e.name);
+    } catch {
+      log.warn(`Cannot read skill directory: ${dirPath}`);
+      return discovered;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dirPath, entry);
+      try {
+        const fileUrl = pathToFileURL(
+          entry.endsWith('.ts') || entry.endsWith('.js') ? fullPath : join(fullPath, 'skill.ts'),
+        ).href;
+        const mod = await import(fileUrl);
+
+        // Look for a factory function or a SkillBase subclass
+        if (typeof mod.createSkill === 'function') {
+          const name = entry.replace(/\.(ts|js)$/, '');
+          this.register(name, mod.createSkill);
+          discovered.push(name);
+        } else if (typeof mod.default === 'function' && mod.default.prototype instanceof SkillBase) {
+          const name = entry.replace(/\.(ts|js)$/, '');
+          this.register(name, (config) => new mod.default(config));
+          discovered.push(name);
+        }
+      } catch (err) {
+        log.debug(`Could not load skill from ${fullPath}: ${err}`);
+      }
+    }
+
+    return discovered;
+  }
+
+  /**
+   * Discover and register skills from all configured search paths.
+   * @returns Array of all newly discovered skill names.
+   */
+  async discoverAll(): Promise<string[]> {
+    const all: string[] = [];
+    for (const path of this.searchPaths) {
+      const found = await this.discoverFromDirectory(path);
+      all.push(...found);
+    }
+    return all;
+  }
+
+  /**
+   * Get the number of registered skills.
+   * @returns The count of registered skills.
+   */
+  get size(): number {
+    return this.registry.size;
+  }
+
+  /**
+   * Clear all registrations.
+   */
+  clear(): void {
+    this.registry.clear();
+  }
+}

package/src/skills/builtin/api_ninjas_trivia.ts

@@ -0,0 +1,230 @@
+/**
+ * API Ninjas Trivia Skill - Fetches trivia questions from the API Ninjas service.
+ *
+ * Tier 2 built-in skill: requires API_NINJAS_KEY environment variable.
+ * Uses the API Ninjas Trivia endpoint to retrieve random trivia questions
+ * with optional category filtering.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** Response shape from the API Ninjas trivia endpoint. */
+interface TriviaResponse {
+  /** Trivia category name. */
+  category: string;
+  /** The trivia question text. */
+  question: string;
+  /** The correct answer. */
+  answer: string;
+}
+
+const VALID_CATEGORIES = [
+  'artliterature',
+  'language',
+  'sciencenature',
+  'general',
+  'fooddrink',
+  'peopleplaces',
+  'geography',
+  'historyholidays',
+  'entertainment',
+  'toysgames',
+  'music',
+  'mathematics',
+  'religionmythology',
+  'sportsleisure',
+] as const;
+
+/**
+ * Fetches trivia questions from the API Ninjas service.
+ *
+ * Tier 2 built-in skill. Requires the `API_NINJAS_KEY` environment variable.
+ * Supports optional `default_category` and `reveal_answer` config options.
+ */
+export class ApiNinjasTriviaSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `default_category` and `reveal_answer`.
+   */
+  constructor(config?: SkillConfig) {
+    super('api_ninjas_trivia', config);
+  }
+
+  /** @returns Manifest declaring API_NINJAS_KEY as required and config schema for category/reveal. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'api_ninjas_trivia',
+      description:
+        'Fetches trivia questions from the API Ninjas service. Supports multiple categories for varied trivia topics.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['trivia', 'api', 'entertainment', 'quiz', 'external'],
+      requiredEnvVars: ['API_NINJAS_KEY'],
+      configSchema: {
+        default_category: {
+          type: 'string',
+          description:
+            'Default trivia category if none is specified by the user.',
+        },
+        reveal_answer: {
+          type: 'boolean',
+          description:
+            'Whether to include the answer in the response. Defaults to false so the AI can quiz the user.',
+          default: false,
+        },
+      },
+    };
+  }
+
+  /** @returns A single `get_trivia` tool that fetches a random trivia question with optional category. */
+  getTools(): SkillToolDefinition[] {
+    const defaultCategory = this.getConfig<string | undefined>(
+      'default_category',
+      undefined,
+    );
+    const revealAnswer = this.getConfig<boolean>('reveal_answer', false);
+
+    return [
+      {
+        name: 'get_trivia',
+        description:
+          'Get a random trivia question. Optionally specify a category to narrow the topic.',
+        parameters: {
+          category: {
+            type: 'string',
+            description:
+              'Trivia category. Available categories: ' +
+              VALID_CATEGORIES.join(', ') +
+              '. If not specified, a random category is used.',
+          },
+        },
+        handler: async (args: Record<string, unknown>) => {
+          const apiKey = process.env['API_NINJAS_KEY'];
+          if (!apiKey) {
+            return new SwaigFunctionResult(
+              'Trivia service is not configured. The API_NINJAS_KEY environment variable is missing.',
+            );
+          }
+
+          let category = (args.category as string | undefined) ?? defaultCategory;
+
+          // Validate category if provided
+          if (category && typeof category === 'string') {
+            const normalized = category.toLowerCase().trim().replace(/[\s_-]/g, '');
+            if (
+              !VALID_CATEGORIES.includes(
+                normalized as (typeof VALID_CATEGORIES)[number],
+              )
+            ) {
+              return new SwaigFunctionResult(
+                `Unknown trivia category "${category}". Available categories: ${VALID_CATEGORIES.join(', ')}.`,
+              );
+            }
+            category = normalized;
+          }
+
+          try {
+            const url = category
+              ? `https://api.api-ninjas.com/v1/trivia?category=${encodeURIComponent(category)}`
+              : 'https://api.api-ninjas.com/v1/trivia';
+
+            const response = await fetch(url, {
+              headers: {
+                'X-Api-Key': apiKey,
+              },
+            });
+
+            if (!response.ok) {
+              return new SwaigFunctionResult(
+                `Failed to fetch trivia: HTTP ${response.status} ${response.statusText}. Please try again later.`,
+              );
+            }
+
+            const data = (await response.json()) as TriviaResponse[];
+
+            if (!Array.isArray(data) || data.length === 0) {
+              return new SwaigFunctionResult(
+                'No trivia questions were returned. Please try again or try a different category.',
+              );
+            }
+
+            const trivia = data[0]!;
+
+            if (revealAnswer) {
+              return new SwaigFunctionResult(
+                `Trivia (${trivia.category}): ${trivia.question} Answer: ${trivia.answer}`,
+              );
+            }
+
+            // When not revealing the answer, provide it in a structured way
+            // so the AI knows the answer but can quiz the user
+            return new SwaigFunctionResult(
+              `Here is a trivia question from the "${trivia.category}" category. ` +
+                `Question: ${trivia.question} ` +
+                `[The correct answer is: ${trivia.answer}. Do not reveal this unless the user attempts an answer or asks for it.]`,
+            );
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Failed to fetch trivia question: ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing trivia capabilities and quiz behavior. */
+  getPromptSections(): SkillPromptSection[] {
+    const revealAnswer = this.getConfig<boolean>('reveal_answer', false);
+
+    const bullets: string[] = [
+      'Use the get_trivia tool to fetch a random trivia question.',
+      `Available categories: ${VALID_CATEGORIES.join(', ')}.`,
+      'If no category is specified, a random category will be selected.',
+    ];
+
+    if (!revealAnswer) {
+      bullets.push(
+        'When you receive a trivia question, ask it to the user and let them try to answer before revealing the correct answer.',
+        'If the user gets it wrong, give them a hint or tell them the correct answer.',
+      );
+    } else {
+      bullets.push(
+        'Trivia answers are included in the response. Share the question and answer with the user.',
+      );
+    }
+
+    bullets.push(
+      'Keep trivia fun and engaging. Encourage the user to try more questions.',
+    );
+
+    return [
+      {
+        title: 'Trivia Questions',
+        body: 'You can fetch and ask trivia questions from a wide range of categories.',
+        bullets,
+      },
+    ];
+  }
+
+  /** @returns Speech recognition hints for trivia-related keywords. */
+  getHints(): string[] {
+    return ['trivia', 'quiz', 'question', 'fun fact'];
+  }
+}
+
+/**
+ * Factory function for creating ApiNinjasTriviaSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new ApiNinjasTriviaSkill instance.
+ */
+export function createSkill(config?: SkillConfig): ApiNinjasTriviaSkill {
+  return new ApiNinjasTriviaSkill(config);
+}