signalwire-agents 0.1.0

package/src/SwmlBuilder.ts

@@ -0,0 +1,62 @@
+/**
+ * SwmlBuilder - Builds SWML (SignalWire Markup Language) documents.
+ *
+ * Produces `{ version: "1.0.0", sections: { main: [...verbs] } }`.
+ */
+
+/** Builds SWML documents composed of verb instructions organized into named sections. */
+export class SwmlBuilder {
+  private document: { version: string; sections: Record<string, unknown[]> };
+
+  /** Creates a new SwmlBuilder with an empty SWML document. */
+  constructor() {
+    this.document = this.createEmpty();
+  }
+
+  private createEmpty() {
+    return { version: '1.0.0', sections: { main: [] as unknown[] } };
+  }
+
+  /** Resets the document to an empty SWML structure. */
+  reset(): void {
+    this.document = this.createEmpty();
+  }
+
+  /**
+   * Appends a verb to the main section.
+   * @param verbName - The SWML verb name (e.g., "answer", "ai").
+   * @param config - The verb's configuration payload.
+   */
+  addVerb(verbName: string, config: unknown): void {
+    this.document.sections['main'].push({ [verbName]: config });
+  }
+
+  /**
+   * Appends a verb to a named section, creating the section if it does not exist.
+   * @param sectionName - The target section name.
+   * @param verbName - The SWML verb name.
+   * @param config - The verb's configuration payload.
+   */
+  addVerbToSection(sectionName: string, verbName: string, config: unknown): void {
+    if (!this.document.sections[sectionName]) {
+      this.document.sections[sectionName] = [];
+    }
+    this.document.sections[sectionName].push({ [verbName]: config });
+  }
+
+  /**
+   * Returns the raw SWML document object.
+   * @returns The document with version and sections.
+   */
+  getDocument(): Record<string, unknown> {
+    return this.document;
+  }
+
+  /**
+   * Serializes the SWML document to a JSON string.
+   * @returns The JSON-encoded SWML document.
+   */
+  renderDocument(): string {
+    return JSON.stringify(this.document);
+  }
+}

package/src/cli/agent-loader.ts

@@ -0,0 +1,122 @@
+/**
+ * Agent discovery via dynamic import for swaig-test CLI.
+ *
+ * Tries multiple strategies to find an AgentBase instance:
+ * 1. Named export `agent`
+ * 2. Default export
+ * 3. Any exported AgentBase instance (duck-typed)
+ * 4. Any exported AgentBase subclass (instantiated)
+ */
+
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+function isAgentInstance(obj: unknown): boolean {
+  if (!obj || typeof obj !== 'object') return false;
+  const a = obj as Record<string, unknown>;
+  return (
+    typeof a['renderSwml'] === 'function' &&
+    typeof a['defineTool'] === 'function' &&
+    typeof a['getPrompt'] === 'function'
+  );
+}
+
+function isAgentClass(obj: unknown): boolean {
+  if (typeof obj !== 'function') return false;
+  const proto = (obj as any).prototype;
+  if (!proto) return false;
+  return (
+    typeof proto['renderSwml'] === 'function' &&
+    typeof proto['defineTool'] === 'function' &&
+    typeof proto['getPrompt'] === 'function'
+  );
+}
+
+async function importModule(agentPath: string): Promise<Record<string, unknown>> {
+  const absPath = resolve(agentPath);
+  const fileUrl = pathToFileURL(absPath).href;
+
+  try {
+    return await import(fileUrl);
+  } catch (err) {
+    throw new Error(`Failed to import agent file: ${absPath}\n${err}`);
+  }
+}
+
+/**
+ * Dynamically import an agent file and resolve an AgentBase instance using duck-typing heuristics.
+ * @param agentPath - Path to the agent module file.
+ * @param agentClass - Optional name of a specific exported class or instance to use.
+ * @returns The resolved AgentBase instance.
+ */
+export async function loadAgent(agentPath: string, agentClass?: string): Promise<unknown> {
+  const mod = await importModule(agentPath);
+
+  // If a specific class name is requested
+  if (agentClass) {
+    const target = mod[agentClass];
+    if (!target) {
+      throw new Error(`Export '${agentClass}' not found in ${agentPath}`);
+    }
+    if (isAgentInstance(target)) return target;
+    if (isAgentClass(target)) {
+      const Cls = target as new (opts: { name: string }) => unknown;
+      return new Cls({ name: agentClass.toLowerCase() });
+    }
+    throw new Error(`Export '${agentClass}' is not an AgentBase instance or class`);
+  }
+
+  // 1. Named export `agent`
+  if (mod['agent'] && isAgentInstance(mod['agent'])) {
+    return mod['agent'];
+  }
+
+  // 2. Default export (instance)
+  if (mod['default'] && isAgentInstance(mod['default'])) {
+    return mod['default'];
+  }
+
+  // 3. Any exported AgentBase instance
+  for (const key of Object.keys(mod)) {
+    if (isAgentInstance(mod[key])) {
+      return mod[key];
+    }
+  }
+
+  // 4. Default export (class) - instantiate
+  if (mod['default'] && isAgentClass(mod['default'])) {
+    const Cls = mod['default'] as new (opts: { name: string }) => unknown;
+    return new Cls({ name: 'cli-agent' });
+  }
+
+  // 5. Any exported AgentBase subclass
+  for (const key of Object.keys(mod)) {
+    if (isAgentClass(mod[key])) {
+      const Cls = mod[key] as new (opts: { name: string }) => unknown;
+      return new Cls({ name: 'cli-agent' });
+    }
+  }
+
+  throw new Error(
+    `Could not find an AgentBase instance or subclass in ${resolve(agentPath)}.\n` +
+    'Export your agent as `export const agent = new AgentBase(...)` or as default export.',
+  );
+}
+
+/**
+ * List all exported agent instances and classes in a module.
+ * @param agentPath - Path to the agent module file.
+ * @returns Array of export names that are AgentBase instances or subclasses.
+ */
+export async function listAgents(agentPath: string): Promise<string[]> {
+  const mod = await importModule(agentPath);
+  const agents: string[] = [];
+
+  for (const key of Object.keys(mod)) {
+    if (isAgentInstance(mod[key]) || isAgentClass(mod[key])) {
+      agents.push(key);
+    }
+  }
+
+  return agents;
+}

package/src/cli/mock-data.ts

@@ -0,0 +1,110 @@
+/**
+ * Mock call data generation for swaig-test CLI.
+ */
+
+import { randomBytes } from 'node:crypto';
+
+/** Options for generating mock call data in CLI testing. */
+export interface MockCallOptions {
+  /** Call transport type. */
+  callType?: 'sip' | 'webrtc';
+  /** Direction of the call. */
+  callDirection?: 'inbound' | 'outbound';
+  /** Current call state (e.g. "active", "ringing", "hold"). */
+  callState?: string;
+  /** Override the auto-generated call ID. */
+  callId?: string;
+  /** Caller's phone number. */
+  fromNumber?: string;
+  /** Destination extension or agent name. */
+  toExtension?: string;
+  /** Additional key-value overrides merged into the post data. */
+  overrides?: Record<string, unknown>;
+}
+
+function randomId(): string {
+  return randomBytes(16).toString('hex');
+}
+
+function randomUuid(): string {
+  const hex = randomBytes(16).toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Generate a full mock POST body simulating an inbound SignalWire call request.
+ * @param opts - Optional overrides for call metadata fields.
+ * @returns A record representing the simulated call POST data.
+ */
+export function generateFakePostData(opts?: MockCallOptions): Record<string, unknown> {
+  const callType = opts?.callType ?? 'webrtc';
+  const callDirection = opts?.callDirection ?? 'inbound';
+  const callState = opts?.callState ?? 'active';
+  const fromNumber = opts?.fromNumber ?? '+15551234567';
+  const toExtension = opts?.toExtension ?? 'test-agent';
+  const callId = opts?.callId ?? randomUuid();
+  const nodeId = randomUuid();
+  const projectId = randomUuid();
+  const spaceId = randomUuid();
+
+  const data: Record<string, unknown> = {
+    call_id: callId,
+    call_type: callType,
+    call_direction: callDirection,
+    call_state: callState,
+    node_id: nodeId,
+    project_id: projectId,
+    space_id: spaceId,
+    caller_id_name: callType === 'sip' ? fromNumber : 'WebRTC User',
+    caller_id_number: fromNumber,
+    call_start_time: new Date().toISOString(),
+    channel_type: callType === 'sip' ? 'phone' : 'web',
+    from: fromNumber,
+    to: toExtension,
+    sip_headers: callType === 'sip' ? {
+      'X-SignalWire-Agent': 'swaig-test-cli',
+    } : undefined,
+    vars: {
+      call_type: callType,
+      direction: callDirection,
+    },
+  };
+
+  // Apply overrides
+  if (opts?.overrides) {
+    Object.assign(data, opts.overrides);
+  }
+
+  return data;
+}
+
+/**
+ * Generate a minimal mock POST body for executing a single SWAIG function.
+ * @param fnName - Name of the SWAIG function to invoke.
+ * @param args - Arguments to pass to the function.
+ * @param opts - Optional call ID and field overrides.
+ * @returns A record representing the minimal POST data for function execution.
+ */
+export function generateMinimalPostData(
+  fnName: string,
+  args?: Record<string, unknown>,
+  opts?: { callId?: string; overrides?: Record<string, unknown> },
+): Record<string, unknown> {
+  const data: Record<string, unknown> = {
+    function: fnName,
+    argument: args ?? {},
+    call_id: opts?.callId ?? randomUuid(),
+    call_type: 'webrtc',
+    call_direction: 'inbound',
+    caller_id_name: 'CLI Test',
+    caller_id_number: '+15551234567',
+    from: '+15551234567',
+    to: 'test-agent',
+  };
+
+  if (opts?.overrides) {
+    Object.assign(data, opts.overrides);
+  }
+
+  return data;
+}