signalwire-agents 0.1.0

package/src/skills/builtin/spider.ts

@@ -0,0 +1,232 @@
+/**
+ * Spider Skill - Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill: requires SPIDER_API_KEY environment variable.
+ * Uses the Spider API to fetch and extract content from web pages,
+ * optionally filtering by CSS selector.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** A single crawl result from the Spider API. */
+interface SpiderResult {
+  /** Raw HTML content of the page. */
+  content?: string;
+  /** Markdown-formatted content. */
+  markdown?: string;
+  /** Plain text content. */
+  text?: string;
+  /** Resolved URL of the crawled page. */
+  url?: string;
+  /** HTTP status code of the crawl. */
+  status?: number;
+  /** Error message if the crawl failed. */
+  error?: string;
+}
+
+/** Response from the Spider API, which may be an array, single result, or error object. */
+type SpiderResponse = SpiderResult[] | SpiderResult | { error: string; message?: string };
+
+/**
+ * Scrapes webpage content using the Spider API.
+ *
+ * Tier 3 built-in skill. Requires the `SPIDER_API_KEY` environment variable.
+ * Extracts text, markdown, or HTML from any public URL, with optional CSS
+ * selector filtering. Supports `max_content_length` config option.
+ */
+export class SpiderSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `max_content_length`.
+   */
+  constructor(config?: SkillConfig) {
+    super('spider', config);
+  }
+
+  /** @returns Manifest declaring SPIDER_API_KEY as required and config schema for max_content_length. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'spider',
+      description:
+        'Scrapes webpage content using the Spider API. Extracts text, markdown, or HTML from any public URL.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['scraping', 'web', 'spider', 'content', 'extraction', 'external'],
+      requiredEnvVars: ['SPIDER_API_KEY'],
+      configSchema: {
+        max_content_length: {
+          type: 'number',
+          description:
+            'Maximum length of returned content in characters. Defaults to 5000.',
+          default: 5000,
+        },
+      },
+    };
+  }
+
+  /** @returns A single `scrape_url` tool that extracts content from a web page. */
+  getTools(): SkillToolDefinition[] {
+    const maxContentLength = this.getConfig<number>('max_content_length', 5000);
+
+    return [
+      {
+        name: 'scrape_url',
+        description:
+          'Scrape and extract content from a web page URL. Returns the page text or markdown content.',
+        parameters: {
+          url: {
+            type: 'string',
+            description: 'The full URL of the web page to scrape (must start with http:// or https://).',
+          },
+          selector: {
+            type: 'string',
+            description:
+              'Optional CSS selector to extract specific content from the page (e.g., "article", ".main-content", "#body").',
+          },
+        },
+        required: ['url'],
+        handler: async (args: Record<string, unknown>) => {
+          const url = args.url as string | undefined;
+          const selector = args.selector as string | undefined;
+
+          if (!url || typeof url !== 'string' || url.trim().length === 0) {
+            return new SwaigFunctionResult('Please provide a URL to scrape.');
+          }
+
+          const trimmedUrl = url.trim();
+          if (!trimmedUrl.startsWith('http://') && !trimmedUrl.startsWith('https://')) {
+            return new SwaigFunctionResult(
+              'Invalid URL. Please provide a full URL starting with http:// or https://.',
+            );
+          }
+
+          const apiKey = process.env['SPIDER_API_KEY'];
+          if (!apiKey) {
+            return new SwaigFunctionResult(
+              'Spider scraping is not configured. The SPIDER_API_KEY environment variable is required.',
+            );
+          }
+
+          try {
+            const requestBody: Record<string, unknown> = {
+              url: trimmedUrl,
+              return_format: 'markdown',
+            };
+
+            if (selector && typeof selector === 'string' && selector.trim().length > 0) {
+              requestBody['css_selector'] = selector.trim();
+            }
+
+            const response = await fetch('https://api.spider.cloud/crawl', {
+              method: 'POST',
+              headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+              },
+              body: JSON.stringify(requestBody),
+            });
+
+            if (!response.ok) {
+              const errorText = await response.text();
+              return new SwaigFunctionResult(
+                `Spider API returned an error (HTTP ${response.status}): ${errorText.slice(0, 300)}`,
+              );
+            }
+
+            const data = (await response.json()) as SpiderResponse;
+
+            // Handle error responses
+            if (!Array.isArray(data) && 'error' in data) {
+              return new SwaigFunctionResult(
+                `Spider scraping failed: ${data.error}`,
+              );
+            }
+
+            // Extract content from result
+            let content = '';
+            const result: SpiderResult = Array.isArray(data) ? data[0] : data;
+
+            if (!result) {
+              return new SwaigFunctionResult(
+                `No content could be extracted from "${trimmedUrl}".`,
+              );
+            }
+
+            if (result.error) {
+              return new SwaigFunctionResult(
+                `Error scraping "${trimmedUrl}": ${result.error}`,
+              );
+            }
+
+            // Prefer markdown > text > content
+            content = result.markdown ?? result.text ?? result.content ?? '';
+
+            if (content.trim().length === 0) {
+              return new SwaigFunctionResult(
+                `The page at "${trimmedUrl}" returned no extractable content.`,
+              );
+            }
+
+            // Truncate if necessary
+            let truncated = false;
+            if (content.length > maxContentLength) {
+              content = content.slice(0, maxContentLength);
+              truncated = true;
+            }
+
+            const parts: string[] = [
+              `Content from ${trimmedUrl}:`,
+              '',
+              content.trim(),
+            ];
+
+            if (truncated) {
+              parts.push('');
+              parts.push(`[Content truncated to ${maxContentLength} characters]`);
+            }
+
+            return new SwaigFunctionResult(parts.join('\n'));
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return new SwaigFunctionResult(
+              `Failed to scrape "${trimmedUrl}": ${message}`,
+            );
+          }
+        },
+      },
+    ];
+  }
+
+  /** @returns Prompt section describing web scraping capabilities and content limits. */
+  getPromptSections(): SkillPromptSection[] {
+    return [
+      {
+        title: 'Web Page Scraping',
+        body: 'You can scrape and extract content from web pages.',
+        bullets: [
+          'Use the scrape_url tool to fetch content from any public web page.',
+          'Provide a full URL starting with http:// or https://.',
+          'Optionally specify a CSS selector to extract specific parts of the page.',
+          'Content is returned as markdown text for easy reading.',
+          `Content is limited to ${this.getConfig<number>('max_content_length', 5000)} characters.`,
+          'Summarize the scraped content for the user rather than reading it verbatim.',
+        ],
+      },
+    ];
+  }
+}
+
+/**
+ * Factory function for creating SpiderSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new SpiderSkill instance.
+ */
+export function createSkill(config?: SkillConfig): SpiderSkill {
+  return new SpiderSkill(config);
+}

package/src/skills/builtin/swml_transfer.ts

@@ -0,0 +1,285 @@
+/**
+ * SWML Transfer Skill - Transfers calls using SWML transfer actions.
+ *
+ * Tier 2 built-in skill: no external dependencies required.
+ * Supports both direct destination transfers and named pattern-based transfers.
+ * Named patterns allow configuring a set of known transfer destinations
+ * that the AI can use by name rather than requiring raw phone numbers or SIP URIs.
+ */
+
+import { SkillBase } from '../SkillBase.js';
+import type {
+  SkillManifest,
+  SkillToolDefinition,
+  SkillPromptSection,
+  SkillConfig,
+} from '../SkillBase.js';
+import { SwaigFunctionResult } from '../../SwaigFunctionResult.js';
+
+/** A named transfer destination pattern with a friendly name and underlying address. */
+interface TransferPattern {
+  /** Friendly name for the destination (used by the AI to refer to it). */
+  name: string;
+  /** SIP URI, phone number, or agent URL to transfer to. */
+  destination: string;
+  /** Optional human-readable description of this destination. */
+  description?: string;
+}
+
+/**
+ * Transfers calls using SWML transfer actions.
+ *
+ * Tier 2 built-in skill with no external dependencies. Supports both direct
+ * destination transfers and named pattern-based transfers configured via the
+ * `patterns` config array. Optionally restricts to named destinations only
+ * via `allow_arbitrary`.
+ */
+export class SwmlTransferSkill extends SkillBase {
+  /**
+   * @param config - Optional configuration; supports `patterns`, `allow_arbitrary`, `default_message`.
+   */
+  constructor(config?: SkillConfig) {
+    super('swml_transfer', config);
+  }
+
+  /** @returns Manifest with config schema for patterns, allow_arbitrary, and default_message. */
+  getManifest(): SkillManifest {
+    return {
+      name: 'swml_transfer',
+      description:
+        'Transfers calls using SWML transfer actions. Supports direct destination transfers and named pattern-based routing.',
+      version: '1.0.0',
+      author: 'SignalWire',
+      tags: ['call-control', 'transfer', 'swml', 'routing'],
+      configSchema: {
+        patterns: {
+          type: 'array',
+          description:
+            'Array of named transfer patterns: { name, destination, description? }. When configured, the AI can transfer to named destinations.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Friendly name for the destination.' },
+              destination: { type: 'string', description: 'SIP URI, phone number, or agent URL.' },
+              description: { type: 'string', description: 'Optional description of this destination.' },
+            },
+            required: ['name', 'destination'],
+          },
+        },
+        allow_arbitrary: {
+          type: 'boolean',
+          description:
+            'Whether to allow transfers to arbitrary destinations not in the patterns list. Defaults to true if no patterns are configured, false if patterns are configured.',
+        },
+        default_message: {
+          type: 'string',
+          description:
+            'Default message to say before transferring. Defaults to "Transferring your call now.".',
+        },
+      },
+    };
+  }
+
+  /** @returns A `transfer_call` tool, plus `list_transfer_destinations` when patterns are configured. */
+  getTools(): SkillToolDefinition[] {
+    const patterns = this.getConfig<TransferPattern[]>('patterns', []);
+    const defaultMessage = this.getConfig<string>(
+      'default_message',
+      'Transferring your call now.',
+    );
+    const allowArbitrary = this.getConfig<boolean | undefined>(
+      'allow_arbitrary',
+      undefined,
+    );
+
+    // If patterns are defined and allow_arbitrary is not explicitly set, default to false
+    const canUseArbitrary =
+      allowArbitrary !== undefined
+        ? allowArbitrary
+        : patterns.length === 0;
+
+    // Build the pattern lookup map
+    const patternMap = new Map<string, TransferPattern>();
+    for (const pattern of patterns) {
+      patternMap.set(pattern.name.toLowerCase(), pattern);
+    }
+
+    const tools: SkillToolDefinition[] = [
+      {
+        name: 'transfer_call',
+        description: this._buildTransferDescription(patterns, canUseArbitrary),
+        parameters: {
+          destination: {
+            type: 'string',
+            description: this._buildDestinationDescription(patterns, canUseArbitrary),
+          },
+          message: {
+            type: 'string',
+            description:
+              'An optional message to say to the caller before the transfer. If not provided, a default transfer message is used.',
+          },
+        },
+        required: ['destination'],
+        handler: (args: Record<string, unknown>) => {
+          const destination = args.destination as string | undefined;
+          const message = (args.message as string | undefined) ?? defaultMessage;
+
+          if (
+            !destination ||
+            typeof destination !== 'string' ||
+            destination.trim().length === 0
+          ) {
+            return new SwaigFunctionResult(
+              'Please specify a destination for the transfer.',
+            );
+          }
+
+          const trimmedDest = destination.trim();
+
+          // Check if this matches a named pattern
+          const matchedPattern = patternMap.get(trimmedDest.toLowerCase());
+
+          if (matchedPattern) {
+            const result = new SwaigFunctionResult(message);
+            result.swmlTransfer(matchedPattern.destination, message);
+            return result;
+          }
+
+          // No matching pattern - check if arbitrary transfers are allowed
+          if (!canUseArbitrary) {
+            const availableNames = patterns
+              .map((p) => `"${p.name}"`)
+              .join(', ');
+            return new SwaigFunctionResult(
+              `Unknown transfer destination "${trimmedDest}". Available destinations: ${availableNames}.`,
+            );
+          }
+
+          // Arbitrary transfer
+          const result = new SwaigFunctionResult(message);
+          result.swmlTransfer(trimmedDest, message);
+          return result;
+        },
+      },
+    ];
+
+    // Add a list_destinations tool if patterns are configured
+    if (patterns.length > 0) {
+      tools.push({
+        name: 'list_transfer_destinations',
+        description:
+          'List all available named transfer destinations that calls can be routed to.',
+        parameters: {},
+        handler: () => {
+          const lines = patterns.map((p) => {
+            const desc = p.description ? ` - ${p.description}` : '';
+            return `${p.name}${desc}`;
+          });
+
+          return new SwaigFunctionResult(
+            `Available transfer destinations:\n${lines.join('\n')}`,
+          );
+        },
+      });
+    }
+
+    return tools;
+  }
+
+  /** @returns Prompt section describing call transfer capabilities and available destinations. */
+  getPromptSections(): SkillPromptSection[] {
+    const patterns = this.getConfig<TransferPattern[]>('patterns', []);
+    const allowArbitrary = this.getConfig<boolean | undefined>(
+      'allow_arbitrary',
+      undefined,
+    );
+    const canUseArbitrary =
+      allowArbitrary !== undefined
+        ? allowArbitrary
+        : patterns.length === 0;
+
+    const bullets: string[] = [
+      'Use the transfer_call tool to transfer the current call to another destination.',
+      'You can optionally provide a message to say to the caller before the transfer.',
+    ];
+
+    if (patterns.length > 0) {
+      const patternNames = patterns.map((p) => `"${p.name}"`).join(', ');
+      bullets.push(
+        `Named transfer destinations are available: ${patternNames}. Use these names as the destination.`,
+      );
+
+      for (const pattern of patterns) {
+        if (pattern.description) {
+          bullets.push(`${pattern.name}: ${pattern.description}`);
+        }
+      }
+
+      if (canUseArbitrary) {
+        bullets.push(
+          'You can also transfer to arbitrary phone numbers or SIP URIs.',
+        );
+      }
+
+      bullets.push(
+        'Use list_transfer_destinations to see all available named destinations.',
+      );
+    } else {
+      bullets.push(
+        'Provide a phone number, SIP URI, or agent URL as the transfer destination.',
+      );
+    }
+
+    return [
+      {
+        title: 'Call Transfer',
+        body: 'You can transfer the current call to another destination.',
+        bullets,
+      },
+    ];
+  }
+
+  /**
+   * Build the tool description based on available patterns.
+   */
+  private _buildTransferDescription(
+    patterns: TransferPattern[],
+    canUseArbitrary: boolean,
+  ): string {
+    if (patterns.length === 0) {
+      return 'Transfer the current call to a specified destination (phone number, SIP URI, or agent URL).';
+    }
+
+    const names = patterns.map((p) => `"${p.name}"`).join(', ');
+    const base = `Transfer the current call. Named destinations: ${names}.`;
+    return canUseArbitrary
+      ? `${base} You may also use arbitrary phone numbers or SIP URIs.`
+      : base;
+  }
+
+  /**
+   * Build the destination parameter description based on available patterns.
+   */
+  private _buildDestinationDescription(
+    patterns: TransferPattern[],
+    canUseArbitrary: boolean,
+  ): string {
+    if (patterns.length === 0) {
+      return 'The transfer destination: a phone number (e.g., +15551234567), SIP URI, or agent URL.';
+    }
+
+    const names = patterns.map((p) => `"${p.name}"`).join(', ');
+    return canUseArbitrary
+      ? `A named destination (${names}) or an arbitrary phone number / SIP URI.`
+      : `One of the named destinations: ${names}.`;
+  }
+}
+
+/**
+ * Factory function for creating SwmlTransferSkill instances.
+ * @param config - Optional skill configuration.
+ * @returns A new SwmlTransferSkill instance.
+ */
+export function createSkill(config?: SkillConfig): SwmlTransferSkill {
+  return new SwmlTransferSkill(config);
+}