signalwire-agents 0.1.0

package/src/PomBuilder.ts

@@ -0,0 +1,298 @@
+/**
+ * PomBuilder - Prompt Object Model for structured prompt sections.
+ *
+ * Built-in replacement for the external signalwire-pom package.
+ * Sections have a title, body, bullets (optionally numbered),
+ * and nested subsections.
+ */
+
+/** Serializable representation of a POM section, used for JSON export. */
+export interface PomSectionData {
+  /** Section heading text. */
+  title?: string;
+  /** Section body paragraph text. */
+  body?: string;
+  /** List of bullet point strings. */
+  bullets?: string[];
+  /** Whether subsections are numbered. */
+  numbered?: boolean;
+  /** Whether bullet points are rendered as a numbered list. */
+  numberedBullets?: boolean;
+  /** Nested child sections. */
+  subsections?: PomSectionData[];
+}
+
+/** A single section in a Prompt Object Model, with optional title, body, bullets, and nested subsections. */
+export class PomSection {
+  /** Section heading text, or null if untitled. */
+  title: string | null;
+  /** Section body paragraph text. */
+  body: string;
+  /** List of bullet point strings. */
+  bullets: string[];
+  /** Nested child sections. */
+  subsections: PomSection[];
+  /** Whether this section is numbered when rendered; null means inherit from parent context. */
+  numbered: boolean | null;
+  /** Whether bullet points are rendered as a numbered list. */
+  numberedBullets: boolean;
+
+  /**
+   * Creates a new PomSection.
+   * @param opts - Optional section configuration.
+   */
+  constructor(opts?: {
+    title?: string | null;
+    body?: string;
+    bullets?: string[];
+    numbered?: boolean | null;
+    numberedBullets?: boolean;
+  }) {
+    this.title = opts?.title ?? null;
+    this.body = opts?.body ?? '';
+    this.bullets = opts?.bullets ?? [];
+    this.subsections = [];
+    this.numbered = opts?.numbered ?? null;
+    this.numberedBullets = opts?.numberedBullets ?? false;
+  }
+
+  /**
+   * Adds a nested subsection to this section.
+   * @param opts - Subsection configuration including title and optional body/bullets.
+   * @returns The newly created child PomSection.
+   */
+  addSubsection(opts: {
+    title: string;
+    body?: string;
+    bullets?: string[];
+    numbered?: boolean;
+    numberedBullets?: boolean;
+  }): PomSection {
+    const sub = new PomSection({
+      title: opts.title,
+      body: opts.body,
+      bullets: opts.bullets,
+      numbered: opts.numbered ?? false,
+      numberedBullets: opts.numberedBullets ?? false,
+    });
+    this.subsections.push(sub);
+    return sub;
+  }
+
+  /**
+   * Serializes this section to a plain data object.
+   * @returns A PomSectionData representation of this section and its subsections.
+   */
+  toDict(): PomSectionData {
+    const data: PomSectionData = {};
+    if (this.body) data.body = this.body;
+    if (this.bullets.length) data.bullets = this.bullets;
+    if (this.subsections.length) data.subsections = this.subsections.map((s) => s.toDict());
+    if (this.title !== null) data.title = this.title;
+    if (this.numbered) data.numbered = this.numbered;
+    if (this.numberedBullets) data.numberedBullets = this.numberedBullets;
+    return data;
+  }
+
+  /**
+   * Renders this section and its subsections as a Markdown string.
+   * @param level - The heading level to start at (default 2 for ##).
+   * @param sectionNumber - Hierarchical numbering prefix for numbered sections.
+   * @returns The rendered Markdown string.
+   */
+  renderMarkdown(level = 2, sectionNumber: number[] = []): string {
+    const lines: string[] = [];
+
+    if (this.title !== null) {
+      const prefix = sectionNumber.length ? `${sectionNumber.join('.')}. ` : '';
+      lines.push(`${'#'.repeat(level)} ${prefix}${this.title}\n`);
+    }
+
+    if (this.body) {
+      lines.push(`${this.body}\n`);
+    }
+
+    for (let i = 0; i < this.bullets.length; i++) {
+      if (this.numberedBullets) {
+        lines.push(`${i + 1}. ${this.bullets[i]}`);
+      } else {
+        lines.push(`- ${this.bullets[i]}`);
+      }
+    }
+    if (this.bullets.length) lines.push('');
+
+    const anyNumbered = this.subsections.some((s) => s.numbered);
+    for (let i = 0; i < this.subsections.length; i++) {
+      const sub = this.subsections[i];
+      let newNumber: number[];
+      let nextLevel: number;
+      if (this.title !== null || sectionNumber.length) {
+        if (anyNumbered && sub.numbered !== false) {
+          newNumber = [...sectionNumber, i + 1];
+        } else {
+          newNumber = sectionNumber;
+        }
+        nextLevel = level + 1;
+      } else {
+        newNumber = sectionNumber;
+        nextLevel = level;
+      }
+      lines.push(sub.renderMarkdown(nextLevel, newNumber));
+    }
+
+    return lines.join('\n');
+  }
+}
+
+/** Builds a structured prompt by composing named POM sections, with Markdown and dict export. */
+export class PomBuilder {
+  private sections: PomSection[] = [];
+  private sectionMap: Map<string, PomSection> = new Map();
+
+  /**
+   * Adds a new top-level section to the prompt.
+   * @param title - The section heading.
+   * @param opts - Optional body, bullets, numbering, and subsection configuration.
+   * @returns This builder for chaining.
+   */
+  addSection(
+    title: string,
+    opts?: {
+      body?: string;
+      bullets?: string[];
+      numbered?: boolean;
+      numberedBullets?: boolean;
+      subsections?: { title: string; body?: string; bullets?: string[] }[];
+    },
+  ): this {
+    const section = new PomSection({
+      title,
+      body: opts?.body,
+      bullets: opts?.bullets,
+      numbered: opts?.numbered,
+      numberedBullets: opts?.numberedBullets,
+    });
+    this.sections.push(section);
+    this.sectionMap.set(title, section);
+
+    if (opts?.subsections) {
+      for (const sub of opts.subsections) {
+        section.addSubsection({
+          title: sub.title,
+          body: sub.body,
+          bullets: sub.bullets,
+        });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Appends body text or bullets to an existing section, creating it if absent.
+   * @param title - The section heading to append to.
+   * @param opts - Body text and/or bullets to add.
+   * @returns This builder for chaining.
+   */
+  addToSection(
+    title: string,
+    opts?: { body?: string; bullet?: string; bullets?: string[] },
+  ): this {
+    if (!this.sectionMap.has(title)) {
+      this.addSection(title);
+    }
+    const section = this.sectionMap.get(title)!;
+    if (opts?.body) {
+      section.body = section.body ? `${section.body}\n\n${opts.body}` : opts.body;
+    }
+    if (opts?.bullet) section.bullets.push(opts.bullet);
+    if (opts?.bullets) section.bullets.push(...opts.bullets);
+    return this;
+  }
+
+  /**
+   * Adds a subsection under an existing parent section, creating the parent if absent.
+   * @param parentTitle - The heading of the parent section.
+   * @param title - The subsection heading.
+   * @param opts - Optional body text and bullets for the subsection.
+   * @returns This builder for chaining.
+   */
+  addSubsection(
+    parentTitle: string,
+    title: string,
+    opts?: { body?: string; bullets?: string[] },
+  ): this {
+    if (!this.sectionMap.has(parentTitle)) {
+      this.addSection(parentTitle);
+    }
+    this.sectionMap.get(parentTitle)!.addSubsection({
+      title,
+      body: opts?.body,
+      bullets: opts?.bullets,
+    });
+    return this;
+  }
+
+  /**
+   * Checks whether a top-level section with the given title exists.
+   * @param title - The section heading to look for.
+   * @returns True if the section exists.
+   */
+  hasSection(title: string): boolean {
+    return this.sectionMap.has(title);
+  }
+
+  /**
+   * Returns a top-level section by title.
+   * @param title - The section heading to retrieve.
+   * @returns The matching PomSection, or undefined if not found.
+   */
+  getSection(title: string): PomSection | undefined {
+    return this.sectionMap.get(title);
+  }
+
+  /**
+   * Recursively searches all sections and subsections for one matching the given title.
+   * @param title - The section heading to search for.
+   * @returns The matching PomSection, or undefined if not found.
+   */
+  findSection(title: string): PomSection | undefined {
+    const recurse = (sections: PomSection[]): PomSection | undefined => {
+      for (const s of sections) {
+        if (s.title === title) return s;
+        const found = recurse(s.subsections);
+        if (found) return found;
+      }
+      return undefined;
+    };
+    return recurse(this.sections);
+  }
+
+  /**
+   * Serializes all sections to an array of plain data objects.
+   * @returns An array of PomSectionData representing all top-level sections.
+   */
+  toDict(): PomSectionData[] {
+    return this.sections.map((s) => s.toDict());
+  }
+
+  /**
+   * Renders all sections as a combined Markdown string.
+   * @returns The complete rendered Markdown prompt text.
+   */
+  renderMarkdown(): string {
+    const anyNumbered = this.sections.some((s) => s.numbered);
+    const parts: string[] = [];
+    let counter = 0;
+    for (const section of this.sections) {
+      let sectionNumber: number[] = [];
+      if (section.title !== null) {
+        counter++;
+        if (anyNumbered && section.numbered !== false) {
+          sectionNumber = [counter];
+        }
+      }
+      parts.push(section.renderMarkdown(2, sectionNumber));
+    }
+    return parts.join('\n');
+  }
+}

package/src/PromptManager.ts

@@ -0,0 +1,133 @@
+/**
+ * PromptManager - Manages agent prompts with POM support.
+ *
+ * Holds either raw prompt text or a PomBuilder for structured prompts.
+ */
+
+import { PomBuilder } from './PomBuilder.js';
+
+/** Manages agent prompt text, supporting both raw text and structured POM-based prompts. */
+export class PromptManager {
+  private rawText: string | null = null;
+  private postPrompt: string | null = null;
+  private pom: PomBuilder | null = null;
+  private usePom: boolean;
+
+  /**
+   * Creates a new PromptManager.
+   * @param usePom - Whether to use structured POM sections (default true).
+   */
+  constructor(usePom = true) {
+    this.usePom = usePom;
+    if (usePom) {
+      this.pom = new PomBuilder();
+    }
+  }
+
+  /**
+   * Sets the raw prompt text, bypassing POM rendering.
+   * @param text - The raw prompt string.
+   */
+  setPromptText(text: string): void {
+    this.rawText = text;
+  }
+
+  /**
+   * Sets the post-prompt text appended after the main prompt.
+   * @param text - The post-prompt string.
+   */
+  setPostPrompt(text: string): void {
+    this.postPrompt = text;
+  }
+
+  /**
+   * Adds a POM section to the prompt, initializing the PomBuilder if needed.
+   * @param title - The section heading.
+   * @param opts - Optional body, bullets, numbering, and subsection configuration.
+   */
+  addSection(
+    title: string,
+    opts?: {
+      body?: string;
+      bullets?: string[];
+      numbered?: boolean;
+      numberedBullets?: boolean;
+      subsections?: { title: string; body?: string; bullets?: string[] }[];
+    },
+  ): void {
+    if (!this.pom) {
+      this.pom = new PomBuilder();
+      this.usePom = true;
+    }
+    this.pom.addSection(title, opts);
+  }
+
+  /**
+   * Appends body text or bullets to an existing POM section, creating it if absent.
+   * @param title - The section heading to append to.
+   * @param opts - Body text and/or bullets to add.
+   */
+  addToSection(
+    title: string,
+    opts?: { body?: string; bullet?: string; bullets?: string[] },
+  ): void {
+    if (!this.pom) {
+      this.pom = new PomBuilder();
+      this.usePom = true;
+    }
+    this.pom.addToSection(title, opts);
+  }
+
+  /**
+   * Adds a subsection under a parent POM section, creating the parent if absent.
+   * @param parentTitle - The heading of the parent section.
+   * @param title - The subsection heading.
+   * @param opts - Optional body text and bullets for the subsection.
+   */
+  addSubsection(
+    parentTitle: string,
+    title: string,
+    opts?: { body?: string; bullets?: string[] },
+  ): void {
+    if (!this.pom) {
+      this.pom = new PomBuilder();
+      this.usePom = true;
+    }
+    this.pom.addSubsection(parentTitle, title, opts);
+  }
+
+  /**
+   * Checks whether a POM section with the given title exists.
+   * @param title - The section heading to look for.
+   * @returns True if the section exists.
+   */
+  hasSection(title: string): boolean {
+    return this.pom?.hasSection(title) ?? false;
+  }
+
+  /**
+   * Returns the fully rendered prompt text, either raw text or POM-rendered Markdown.
+   * @returns The prompt string, or empty string if nothing is set.
+   */
+  getPrompt(): string {
+    if (this.rawText !== null) return this.rawText;
+    if (this.pom) return this.pom.renderMarkdown();
+    return '';
+  }
+
+  /**
+   * Returns the post-prompt text.
+   * @returns The post-prompt string, or null if not set.
+   */
+  getPostPrompt(): string | null {
+    return this.postPrompt;
+  }
+
+  /**
+   * Returns the underlying PomBuilder instance, if POM mode is active.
+   * @returns The PomBuilder, or null if POM is not in use.
+   */
+  getPomBuilder(): PomBuilder | null {
+    return this.pom;
+  }
+}

package/src/SchemaUtils.ts

@@ -0,0 +1,170 @@
+/**
+ * SchemaUtils - JSON Schema validation for SWML documents.
+ *
+ * Provides basic structural validation of rendered SWML.
+ * Set SWML_SKIP_SCHEMA_VALIDATION=true to disable.
+ */
+
+/** Result of validating a SWML document. */
+export interface ValidationResult {
+  /** Whether the document passed all validation checks. */
+  valid: boolean;
+  /** List of human-readable error messages; empty when valid. */
+  errors: string[];
+}
+
+// Basic SWML structure expectations
+const REQUIRED_TOP_LEVEL = ['version', 'sections'];
+const VALID_VERSIONS = ['1.0.0'];
+
+/** Validates SWML documents against structural rules with an LRU-style result cache. */
+export class SchemaUtils {
+  private skipValidation: boolean;
+  private cache: Map<string, ValidationResult> = new Map();
+  private maxCacheSize: number;
+
+  /**
+   * Create a SchemaUtils instance.
+   * @param opts - Optional settings for skipping validation or limiting cache size.
+   */
+  constructor(opts?: { skipValidation?: boolean; maxCacheSize?: number }) {
+    this.skipValidation = opts?.skipValidation ?? (process.env['SWML_SKIP_SCHEMA_VALIDATION'] === 'true');
+    this.maxCacheSize = opts?.maxCacheSize ?? 100;
+  }
+
+  /**
+   * Validate a SWML document against structural rules.
+   * @param swml - The SWML document as a JSON string or parsed object.
+   * @returns The validation result indicating success or a list of errors.
+   */
+  validate(swml: string | Record<string, unknown>): ValidationResult {
+    if (this.skipValidation) {
+      return { valid: true, errors: [] };
+    }
+
+    const swmlStr = typeof swml === 'string' ? swml : JSON.stringify(swml);
+
+    // Check cache
+    const cached = this.cache.get(swmlStr);
+    if (cached) return cached;
+
+    const errors: string[] = [];
+    let doc: Record<string, unknown>;
+
+    try {
+      doc = typeof swml === 'string' ? JSON.parse(swml) : swml;
+    } catch {
+      const result: ValidationResult = { valid: false, errors: ['Invalid JSON'] };
+      this.cacheResult(swmlStr, result);
+      return result;
+    }
+
+    // Check top-level required keys
+    for (const key of REQUIRED_TOP_LEVEL) {
+      if (!(key in doc)) {
+        errors.push(`Missing required top-level key: ${key}`);
+      }
+    }
+
+    // Check version
+    if (doc['version'] && !VALID_VERSIONS.includes(doc['version'] as string)) {
+      errors.push(`Invalid version: ${doc['version']}. Expected one of: ${VALID_VERSIONS.join(', ')}`);
+    }
+
+    // Check sections
+    if (doc['sections']) {
+      if (typeof doc['sections'] !== 'object' || Array.isArray(doc['sections'])) {
+        errors.push('sections must be an object');
+      } else {
+        const sections = doc['sections'] as Record<string, unknown>;
+        if (!('main' in sections)) {
+          errors.push('sections must contain a "main" section');
+        }
+        // Validate each section is an array
+        for (const [name, section] of Object.entries(sections)) {
+          if (!Array.isArray(section)) {
+            errors.push(`Section "${name}" must be an array`);
+          }
+        }
+      }
+    }
+
+    // Validate AI verb structure if present
+    if (doc['sections'] && typeof doc['sections'] === 'object') {
+      const sections = doc['sections'] as Record<string, unknown[]>;
+      const main = sections['main'];
+      if (Array.isArray(main)) {
+        for (const verb of main) {
+          if (typeof verb === 'object' && verb !== null && 'ai' in verb) {
+            this.validateAiVerb((verb as Record<string, unknown>)['ai'] as Record<string, unknown>, errors);
+          }
+        }
+      }
+    }
+
+    const result: ValidationResult = {
+      valid: errors.length === 0,
+      errors,
+    };
+    this.cacheResult(swmlStr, result);
+    return result;
+  }
+
+  private validateAiVerb(ai: Record<string, unknown>, errors: string[]): void {
+    if (!ai) return;
+
+    // Prompt must have text
+    if (ai['prompt']) {
+      const prompt = ai['prompt'] as Record<string, unknown>;
+      if (typeof prompt === 'object' && !prompt['text']) {
+        errors.push('AI prompt must have a "text" field');
+      }
+    }
+
+    // SWAIG validation
+    if (ai['SWAIG']) {
+      const swaig = ai['SWAIG'] as Record<string, unknown>;
+      if (swaig['functions'] && !Array.isArray(swaig['functions'])) {
+        errors.push('SWAIG functions must be an array');
+      }
+      if (Array.isArray(swaig['functions'])) {
+        for (let i = 0; i < (swaig['functions'] as unknown[]).length; i++) {
+          const fn = (swaig['functions'] as Record<string, unknown>[])[i];
+          if (!fn['function']) {
+            errors.push(`SWAIG function at index ${i} missing "function" name`);
+          }
+        }
+      }
+    }
+
+    // Post-prompt validation
+    if (ai['post_prompt']) {
+      const pp = ai['post_prompt'] as Record<string, unknown>;
+      if (typeof pp === 'object' && !pp['text']) {
+        errors.push('AI post_prompt must have a "text" field');
+      }
+    }
+  }
+
+  /** Clear the validation cache */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Get the number of cached validation results.
+   * @returns The current cache entry count.
+   */
+  getCacheSize(): number {
+    return this.cache.size;
+  }
+
+  private cacheResult(key: string, result: ValidationResult): void {
+    if (this.cache.size >= this.maxCacheSize) {
+      // Remove oldest entry
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey) this.cache.delete(firstKey);
+    }
+    this.cache.set(key, result);
+  }
+}