signalwire-agents 0.1.0

package/src/skills/builtin/info_gatherer.ts

@@ -0,0 +1,331 @@
+/**
+ * Info Gatherer Skill - Collects structured information from the user.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Dynamically generates a save_info tool based on configured fields.
+ * Fields can have optional validation patterns and required/optional flags.
+ * Useful for collecting user details like name, email, phone, address, etc.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** Definition of a single data field to be collected from the user. */
+interface FieldDefinition {
+  /** Field name used as the parameter key. */
+  name: string;
+  /** Description of what this field collects. */
+  description: string;
+  /** Whether this field must be provided. */
+  required?: boolean;
+  /** Optional regex pattern for validating the field value. */
+  validation?: string;
+  /** Parameter type for the tool schema (defaults to "string"). */
+  type?: string;
+}
+
+/** Key-value map of information gathered from a user during a call. */
+interface GatheredInfo {
+  [key: string]: unknown;
+}
+
+/**
+ * Collects structured information from the user based on configurable fields.
+ *
+ * Tier 2 built-in skill with no external dependencies. Dynamically generates
+ * a `save_info` tool based on the `fields` config array. Fields support
+ * optional validation patterns and required/optional flags. Data is stored
+ * per-call and optionally merged into global data.
+ */
+export class InfoGathererSkill extends SkillBase {
+  private gatheredData: Map<string, GatheredInfo> = new Map();
+
+  /**
+   * @param config - Optional configuration; supports `fields`, `purpose`, `confirmation_message`, `store_globally`.
+   */
+  constructor(config?: SkillConfig) {
+    super('info_gatherer', config);
+  }
+
+  /** @returns Manifest with config schema for fields, purpose, confirmation_message, and store_globally. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'info_gatherer',
+      description:
+        'Collects structured information from the user based on configurable fields. Validates and stores gathered data.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['data-collection', 'form', 'information', 'utility'],
+      configSchema: {
+        fields: {
+          type: 'array',
+          description:
+            'Array of field definitions to collect: { name, description, required?, validation?, type? }.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Field name (used as the parameter key).' },
+              description: { type: 'string', description: 'Description of what this field collects.' },
+              required: { type: 'boolean', description: 'Whether this field is required. Defaults to false.' },
+              validation: {
+                type: 'string',
+                description: 'Optional regex pattern for validation (e.g., "^[\\\\w.+-]+@[\\\\w-]+\\\\.[\\\\w.]+$" for email).',
+              },
+              type: {
+                type: 'string',
+                description: 'Parameter type for the tool schema. Defaults to "string".',
+              },
+            },
+            required: ['name', 'description'],
+          },
+        },
+        purpose: {
+          type: 'string',
+          description:
+            'A description of why this information is being collected (shown in prompt).',
+        },
+        confirmation_message: {
+          type: 'string',
+          description:
+            'Custom message returned after successful info collection.',
+        },
+        store_globally: {
+          type: 'boolean',
+          description:
+            'Whether to store gathered info in global data. Defaults to false.',
+        },
+      },
+    };
+  }
+
+  /** @returns A `save_info` tool (dynamic params from config) and a `get_gathered_info` retrieval tool. */
+  getTools(): SkillToolDefinition[] {
+    const fields = this.getConfig<FieldDefinition[]>('fields', []);
+    const confirmationMessage = this.getConfig<string>(
+      'confirmation_message',
+      'Information has been saved successfully.',
+    );
+    const storeGlobally = this.getConfig<boolean>('store_globally', false);
+
+    if (fields.length === 0) {
+      return [];
+    }
+
+    // Build dynamic parameters from field definitions
+    const parameters: Record<string, unknown> = {};
+    const requiredParams: string[] = [];
+
+    for (const field of fields) {
+      parameters[field.name] = {
+        type: field.type ?? 'string',
+        description: field.description,
+      };
+
+      if (field.required) {
+        requiredParams.push(field.name);
+      }
+    }
+
+    const tools: SkillToolDefinition[] = [
+      {
+        name: 'save_info',
+        description:
+          'Save information gathered from the user. Call this once you have collected the required fields.',
+        parameters,
+        required: requiredParams.length > 0 ? requiredParams : undefined,
+        handler: (args: Record<string, unknown>, rawData: Record<string, unknown>) => {
+          const errors: string[] = [];
+          const collected: GatheredInfo = {};
+
+          // Validate each field
+          for (const field of fields) {
+            const value = args[field.name];
+
+            // Check required fields
+            if (field.required) {
+              if (value === undefined || value === null || (typeof value === 'string' && value.trim().length === 0)) {
+                errors.push(`"${field.name}" is required but was not provided.`);
+                continue;
+              }
+            }
+
+            // Skip optional fields that weren't provided
+            if (value === undefined || value === null) {
+              continue;
+            }
+
+            // Validate against pattern if specified
+            if (field.validation && typeof value === 'string') {
+              try {
+                const regex = new RegExp(field.validation);
+                if (!regex.test(value)) {
+                  errors.push(
+                    `"${field.name}" value "${value}" does not match the expected format.`,
+                  );
+                  continue;
+                }
+              } catch {
+                // If regex is invalid, skip validation
+              }
+            }
+
+            collected[field.name] = typeof value === 'string' ? value.trim() : value;
+          }
+
+          if (errors.length > 0) {
+            return new SwaigFunctionResult(
+              `Could not save information due to validation errors:\n${errors.join('\n')}\nPlease correct these fields and try again.`,
+            );
+          }
+
+          if (Object.keys(collected).length === 0) {
+            return new SwaigFunctionResult(
+              'No information was provided. Please collect at least one field before saving.',
+            );
+          }
+
+          // Store the gathered data keyed by call ID if available
+          const callId = (rawData['call_id'] as string | undefined) ?? 'default';
+          this.gatheredData.set(callId, {
+            ...this.gatheredData.get(callId),
+            ...collected,
+          });
+
+          // Build confirmation with collected fields summary
+          const fieldSummary = Object.entries(collected)
+            .map(([key, val]) => `${key}: ${val}`)
+            .join(', ');
+
+          const result = new SwaigFunctionResult(
+            `${confirmationMessage} Saved: ${fieldSummary}.`,
+          );
+
+          // Optionally store in global data
+          if (storeGlobally) {
+            result.updateGlobalData({ gathered_info: collected });
+          }
+
+          return result;
+        },
+      },
+      {
+        name: 'get_gathered_info',
+        description:
+          'Retrieve previously gathered information for the current call. Useful to review what has already been collected.',
+        parameters: {},
+        handler: (_args: Record<string, unknown>, rawData: Record<string, unknown>) => {
+          const callId = (rawData['call_id'] as string | undefined) ?? 'default';
+          const info = this.gatheredData.get(callId);
+
+          if (!info || Object.keys(info).length === 0) {
+            return new SwaigFunctionResult(
+              'No information has been gathered yet for this call.',
+            );
+          }
+
+          const summary = Object.entries(info)
+            .map(([key, val]) => `${key}: ${val}`)
+            .join(', ');
+
+          return new SwaigFunctionResult(
+            `Previously gathered information: ${summary}.`,
+          );
+        },
+      },
+    ];
+
+    return tools;
+  }
+
+  /** @returns Prompt section listing required/optional fields and collection instructions. */
+  getPromptSections(): SkillPromptSection[] {
+    const fields = this.getConfig<FieldDefinition[]>('fields', []);
+    const purpose = this.getConfig<string | undefined>('purpose', undefined);
+
+    if (fields.length === 0) {
+      return [];
+    }
+
+    const requiredFields = fields.filter((f) => f.required);
+    const optionalFields = fields.filter((f) => !f.required);
+
+    const bullets: string[] = [];
+
+    if (purpose) {
+      bullets.push(`Purpose: ${purpose}`);
+    }
+
+    bullets.push(
+      'Use the save_info tool to store information once you have collected it from the user.',
+    );
+
+    if (requiredFields.length > 0) {
+      const reqNames = requiredFields.map((f) => `"${f.name}"`).join(', ');
+      bullets.push(
+        `Required fields (must be collected): ${reqNames}.`,
+      );
+    }
+
+    if (optionalFields.length > 0) {
+      const optNames = optionalFields.map((f) => `"${f.name}"`).join(', ');
+      bullets.push(
+        `Optional fields (collect if available): ${optNames}.`,
+      );
+    }
+
+    // Add field descriptions
+    for (const field of fields) {
+      const reqLabel = field.required ? ' (required)' : ' (optional)';
+      bullets.push(`${field.name}${reqLabel}: ${field.description}`);
+    }
+
+    bullets.push(
+      'Ask for information naturally in conversation rather than as a list of questions.',
+      'Use get_gathered_info to review what has already been collected.',
+      'Once all required fields are gathered, call save_info to store the data.',
+    );
+
+    return [
+      {
+        title: 'Information Collection',
+        body: 'You need to collect specific information from the user during this conversation.',
+        bullets,
+      },
+    ];
+  }
+
+  /**
+   * Get all gathered data, keyed by call ID.
+   * @returns A copy of the internal gathered data map.
+   */
+  getAllGatheredData(): Map<string, GatheredInfo> {
+    return new Map(this.gatheredData);
+  }
+
+  /**
+   * Clear gathered data for a specific call or all calls.
+   * @param callId - If provided, clear data for this call only; otherwise clear all.
+   */
+  clearGatheredData(callId?: string): void {
+    if (callId) {
+      this.gatheredData.delete(callId);
+    } else {
+      this.gatheredData.clear();
+    }
+  }
+}
+
+/**
+ * Factory function for creating InfoGathererSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new InfoGathererSkill instance.
+ */
+export function createSkill(config?: SkillConfig): InfoGathererSkill {
+  return new InfoGathererSkill(config);
+}

package/src/skills/builtin/joke.ts

@@ -0,0 +1,180 @@
+/**
+ * Joke Skill - Tells random jokes from a built-in collection.
+ *
+ * Tier 1 built-in skill: no external dependencies required.
+ * Contains a curated set of jokes across multiple categories.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** Internal representation of a joke with setup and punchline. */
+interface Joke {
+  /** Joke category (e.g., "general", "programming", "dad"). */
+  category: string;
+  /** The joke setup line. */
+  setup: string;
+  /** The joke punchline. */
+  punchline: string;
+}
+
+const JOKES: Joke[] = [
+  // General
+  {
+    category: 'general',
+    setup: 'Why did the scarecrow win an award?',
+    punchline: 'Because he was outstanding in his field.',
+  },
+  {
+    category: 'general',
+    setup: 'What do you call a fake noodle?',
+    punchline: 'An impasta.',
+  },
+  {
+    category: 'general',
+    setup: 'Why did the bicycle fall over?',
+    punchline: 'Because it was two-tired.',
+  },
+  // Programming
+  {
+    category: 'programming',
+    setup: 'Why do programmers prefer dark mode?',
+    punchline: 'Because light attracts bugs.',
+  },
+  {
+    category: 'programming',
+    setup: 'What is a programmer\'s favorite hangout place?',
+    punchline: 'Foo Bar.',
+  },
+  {
+    category: 'programming',
+    setup: 'Why do Java developers wear glasses?',
+    punchline: 'Because they can\'t C#.',
+  },
+  {
+    category: 'programming',
+    setup: 'How many programmers does it take to change a light bulb?',
+    punchline: 'None. That\'s a hardware problem.',
+  },
+  // Dad jokes
+  {
+    category: 'dad',
+    setup: 'I\'m reading a book about anti-gravity.',
+    punchline: 'It\'s impossible to put down.',
+  },
+  {
+    category: 'dad',
+    setup: 'What did the ocean say to the beach?',
+    punchline: 'Nothing, it just waved.',
+  },
+  {
+    category: 'dad',
+    setup: 'Why don\'t skeletons fight each other?',
+    punchline: 'They don\'t have the guts.',
+  },
+];
+
+const VALID_CATEGORIES = ['general', 'programming', 'dad'];
+
+/**
+ * Tells random jokes from a curated built-in collection.
+ *
+ * Tier 1 built-in skill with no external dependencies. Includes general,
+ * programming, and dad joke categories.
+ */
+export class JokeSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration (no config keys used by this skill).
+   */
+  constructor(config?: SkillConfig) {
+    super('joke', config);
+  }
+
+  /** @returns Manifest with skill metadata and tags. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'joke',
+      description: 'Tells random jokes from a built-in collection across several categories.',
+      version: '1.0.0',
+      tags: ['entertainment', 'joke', 'humor'],
+    };
+  }
+
+  /** @returns A single `tell_joke` tool that returns a random joke with optional category filter. */
+  getTools(): SkillToolDefinition[] {
+    return [
+      {
+        name: 'tell_joke',
+        description:
+          'Tell a random joke. Optionally specify a category to get a joke from that category.',
+        parameters: {
+          category: {
+            type: 'string',
+            description:
+              'Joke category: "general", "programming", or "dad". If not specified, a random joke from any category is returned.',
+          },
+        },
+        handler: (args: Record<string, unknown>) => {
+          const category = args.category as string | undefined;
+
+          let pool = JOKES;
+
+          if (category && typeof category === 'string') {
+            const normalized = category.toLowerCase().trim();
+
+            if (!VALID_CATEGORIES.includes(normalized)) {
+              return new SwaigFunctionResult(
+                `Unknown joke category "${category}". Available categories are: ${VALID_CATEGORIES.join(', ')}.`,
+              );
+            }
+
+            pool = JOKES.filter((j) => j.category === normalized);
+          }
+
+          if (pool.length === 0) {
+            return new SwaigFunctionResult(
+              'Sorry, I could not find any jokes for that category.',
+            );
+          }
+
+          const joke = pool[Math.floor(Math.random() * pool.length)]!;
+
+          return new SwaigFunctionResult(
+            `${joke.setup} ... ${joke.punchline}`,
+          );
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section instructing the AI how to deliver jokes. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Jokes',
+        body: 'You have the ability to tell jokes to lighten the mood.',
+        bullets: [
+          'Use the tell_joke tool when a user asks for a joke or when humor is appropriate.',
+          'Available joke categories: general, programming, and dad jokes.',
+          'If the user asks for a specific type of joke, pass the category parameter.',
+          'Deliver the joke naturally: say the setup, pause briefly, then deliver the punchline.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating JokeSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new JokeSkill instance.
+ */
+export function createSkill(config?: SkillConfig): JokeSkill {
+  return new JokeSkill(config);
+}

package/src/skills/builtin/math.ts

@@ -0,0 +1,150 @@
+/**
+ * Math Skill - Evaluates mathematical expressions safely.
+ *
+ * Tier 1 built-in skill: no external dependencies required.
+ * Uses a safe parser that only allows digits, basic arithmetic operators,
+ * parentheses, decimal points, and spaces.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/**
+ * Validate that an expression contains only safe mathematical characters.
+ * Allowed: digits (0-9), operators (+, -, *, /, ^, %), parentheses, decimal points, spaces.
+ * @param expr - The expression string to validate.
+ * @returns True if the expression contains only allowed characters.
+ */
+function isSafeExpression(expr: string): boolean {
+  return /^[\d+\-*/^%().\s]+$/.test(expr);
+}
+
+/**
+ * Safely evaluate a mathematical expression.
+ * Replaces ^ with ** for exponentiation, then evaluates using Function constructor
+ * after validating the expression contains only safe characters.
+ * @param expr - The mathematical expression to evaluate.
+ * @returns The computed numeric result.
+ */
+function safeEvaluate(expr: string): number {
+  const trimmed = expr.trim();
+
+  if (trimmed.length === 0) {
+    throw new Error('Expression is empty.');
+  }
+
+  if (!isSafeExpression(trimmed)) {
+    throw new Error(
+      'Expression contains invalid characters. Only digits, operators (+, -, *, /, ^, %), parentheses, decimal points, and spaces are allowed.',
+    );
+  }
+
+  // Replace ^ with ** for exponentiation support
+  const normalized = trimmed.replace(/\^/g, '**');
+
+  // Use Function constructor (safer than eval, and we have already validated the input)
+  const fn = new Function(`"use strict"; return (${normalized});`) as () => unknown;
+  const result = fn();
+
+  if (typeof result !== 'number' || !isFinite(result)) {
+    throw new Error('Expression did not evaluate to a finite number.');
+  }
+
+  return result;
+}
+
+/**
+ * Evaluates mathematical expressions safely using a sandboxed parser.
+ *
+ * Tier 1 built-in skill with no external dependencies. Only allows digits,
+ * basic arithmetic operators, parentheses, decimal points, and spaces.
+ */
+export class MathSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration (no config keys used by this skill).
+   */
+  constructor(config?: SkillConfig) {
+    super('math', config);
+  }
+
+  /** @returns Manifest with skill metadata and tags. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'math',
+      description: 'Evaluates mathematical expressions with basic arithmetic operations.',
+      version: '1.0.0',
+      tags: ['utility', 'math', 'calculator'],
+    };
+  }
+
+  /** @returns A single `calculate` tool that evaluates a math expression string. */
+  getTools(): SkillToolDefinition[] {
+    return [
+      {
+        name: 'calculate',
+        description:
+          'Evaluate a mathematical expression. Supports basic arithmetic: addition (+), subtraction (-), multiplication (*), division (/), exponentiation (^), modulo (%), and parentheses for grouping.',
+        parameters: {
+          expression: {
+            type: 'string',
+            description:
+              'The mathematical expression to evaluate (e.g., "2 + 3 * 4", "100 / (5 + 5)", "2 ^ 10").',
+          },
+        },
+        required: ['expression'],
+        handler: (args: Record<string, unknown>) => {
+          const expression = args.expression as string | undefined;
+
+          if (!expression || typeof expression !== 'string') {
+            return new SwaigFunctionResult(
+              'Please provide a mathematical expression to evaluate.',
+            );
+          }
+
+          try {
+            const result = safeEvaluate(expression);
+            return new SwaigFunctionResult(
+              `The result of ${expression.trim()} is ${result}.`,
+            );
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Could not evaluate the expression "${expression}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section instructing the AI how to use the calculate tool. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Mathematical Calculations',
+        body: 'You have the ability to perform mathematical calculations.',
+        bullets: [
+          'Use the calculate tool to evaluate mathematical expressions.',
+          'Supported operations: addition (+), subtraction (-), multiplication (*), division (/), exponentiation (^), and modulo (%).',
+          'Parentheses can be used for grouping, e.g., (2 + 3) * 4.',
+          'When a user asks you to compute something, use this tool rather than attempting mental math.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating MathSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new MathSkill instance.
+ */
+export function createSkill(config?: SkillConfig): MathSkill {
+  return new MathSkill(config);
+}