signalwire-agents 0.1.0

package/dist/Logger.js

@@ -0,0 +1,191 @@
+/**
+ * Logger - Structured logger with env-var-based configuration.
+ *
+ * SIGNALWIRE_LOG_LEVEL: debug | info | warn | error (default: info)
+ * SIGNALWIRE_LOG_MODE: off to suppress all logging
+ * SIGNALWIRE_LOG_FORMAT: text | json (default: text)
+ * SIGNALWIRE_LOG_COLOR: true | false (default: true when TTY)
+ */
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+let globalLevel = process.env['SIGNALWIRE_LOG_LEVEL'] ?? 'info';
+let globalSuppressed = process.env['SIGNALWIRE_LOG_MODE'] === 'off';
+let globalFormat = process.env['SIGNALWIRE_LOG_FORMAT'] ?? 'text';
+let globalColor = process.env['SIGNALWIRE_LOG_COLOR'] !== undefined
+    ? process.env['SIGNALWIRE_LOG_COLOR'] === 'true'
+    : (process.stdout?.isTTY ?? false);
+// ANSI color codes
+const COLORS = {
+    debug: '\x1b[36m', // cyan
+    info: '\x1b[32m', // green
+    warn: '\x1b[33m', // yellow
+    error: '\x1b[31m', // red
+};
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+/**
+ * Set the minimum log level for all loggers.
+ * @param level - The minimum severity level to emit.
+ */
+export function setGlobalLogLevel(level) {
+    globalLevel = level;
+}
+/**
+ * Suppress or unsuppress all log output globally.
+ * @param suppress - True to suppress, false to restore (default true).
+ */
+export function suppressAllLogs(suppress = true) {
+    globalSuppressed = suppress;
+}
+/**
+ * Set the output format for all loggers.
+ * @param format - Either 'text' (human-readable) or 'json' (structured).
+ */
+export function setGlobalLogFormat(format) {
+    globalFormat = format;
+}
+/**
+ * Enable or disable ANSI color codes in text-format output.
+ * @param enabled - True to enable colors, false to disable.
+ */
+export function setGlobalLogColor(enabled) {
+    globalColor = enabled;
+}
+/** Reset all logging settings to their environment-variable-based defaults. */
+export function resetLoggingConfiguration() {
+    globalLevel = process.env['SIGNALWIRE_LOG_LEVEL'] ?? 'info';
+    globalSuppressed = process.env['SIGNALWIRE_LOG_MODE'] === 'off';
+    globalFormat = process.env['SIGNALWIRE_LOG_FORMAT'] ?? 'text';
+    globalColor = process.env['SIGNALWIRE_LOG_COLOR'] !== undefined
+        ? process.env['SIGNALWIRE_LOG_COLOR'] === 'true'
+        : (process.stdout?.isTTY ?? false);
+}
+/** Structured logger that respects global level, format, and color settings. */
+export class Logger {
+    name;
+    context;
+    /**
+     * Create a new Logger instance.
+     * @param name - Logger name shown in log output.
+     * @param context - Optional key-value pairs included in every log entry.
+     */
+    constructor(name, context) {
+        this.name = name;
+        this.context = context ?? {};
+    }
+    /**
+     * Create a child logger with additional bound context fields merged into the parent's context.
+     * @param context - Key-value pairs to merge into the child logger's context.
+     * @returns A new Logger instance with the merged context.
+     */
+    bind(context) {
+        return new Logger(this.name, { ...this.context, ...context });
+    }
+    /**
+     * Log a message at the debug level.
+     * @param msg - The log message.
+     * @param data - Optional structured data to include.
+     */
+    debug(msg, data) {
+        this.log('debug', msg, data);
+    }
+    /**
+     * Log a message at the info level.
+     * @param msg - The log message.
+     * @param data - Optional structured data to include.
+     */
+    info(msg, data) {
+        this.log('info', msg, data);
+    }
+    /**
+     * Log a message at the warn level.
+     * @param msg - The log message.
+     * @param data - Optional structured data to include.
+     */
+    warn(msg, data) {
+        this.log('warn', msg, data);
+    }
+    /**
+     * Log a message at the error level.
+     * @param msg - The log message.
+     * @param data - Optional structured data to include.
+     */
+    error(msg, data) {
+        this.log('error', msg, data);
+    }
+    log(level, msg, data) {
+        if (globalSuppressed)
+            return;
+        if (LEVELS[level] < LEVELS[globalLevel])
+            return;
+        const merged = (data && Object.keys(data).length) || Object.keys(this.context).length
+            ? { ...this.context, ...data }
+            : undefined;
+        if (globalFormat === 'json') {
+            this.logJson(level, msg, merged);
+        }
+        else {
+            this.logText(level, msg, merged);
+        }
+    }
+    logText(level, msg, data) {
+        const levelStr = level.toUpperCase();
+        let prefix;
+        if (globalColor) {
+            prefix = `${COLORS[level]}[${levelStr}]${RESET} ${DIM}[${this.name}]${RESET}`;
+        }
+        else {
+            prefix = `[${levelStr}] [${this.name}]`;
+        }
+        const suffix = data && Object.keys(data).length ? ' ' + JSON.stringify(data) : '';
+        const line = `${prefix} ${msg}${suffix}`;
+        switch (level) {
+            case 'debug':
+                console.debug(line);
+                break;
+            case 'info':
+                console.info(line);
+                break;
+            case 'warn':
+                console.warn(line);
+                break;
+            case 'error':
+                console.error(line);
+                break;
+        }
+    }
+    logJson(level, msg, data) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            logger: this.name,
+            message: msg,
+        };
+        if (data && Object.keys(data).length) {
+            Object.assign(entry, data);
+        }
+        const line = JSON.stringify(entry);
+        switch (level) {
+            case 'debug':
+                console.debug(line);
+                break;
+            case 'info':
+                console.info(line);
+                break;
+            case 'warn':
+                console.warn(line);
+                break;
+            case 'error':
+                console.error(line);
+                break;
+        }
+    }
+}
+/**
+ * Create a new Logger instance with the given name.
+ * @param name - Logger name shown in log output.
+ * @returns A new Logger instance.
+ */
+export function getLogger(name) {
+    return new Logger(name);
+}
+//# sourceMappingURL=Logger.js.map

package/dist/Logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Logger.js","sourceRoot":"","sources":["../src/Logger.ts"],"names":[],"mappings":"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"}

package/dist/PomBuilder.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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 declare 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;
+    });
+    /**
+     * 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;
+    /**
+     * Serializes this section to a plain data object.
+     * @returns A PomSectionData representation of this section and its subsections.
+     */
+    toDict(): PomSectionData;
+    /**
+     * 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?: number, sectionNumber?: number[]): string;
+}
+/** Builds a structured prompt by composing named POM sections, with Markdown and dict export. */
+export declare class PomBuilder {
+    private sections;
+    private sectionMap;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Serializes all sections to an array of plain data objects.
+     * @returns An array of PomSectionData representing all top-level sections.
+     */
+    toDict(): PomSectionData[];
+    /**
+     * Renders all sections as a combined Markdown string.
+     * @returns The complete rendered Markdown prompt text.
+     */
+    renderMarkdown(): string;
+}

package/dist/PomBuilder.js

@@ -0,0 +1,249 @@
+/**
+ * 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.
+ */
+/** 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;
+    /** Section body paragraph text. */
+    body;
+    /** List of bullet point strings. */
+    bullets;
+    /** Nested child sections. */
+    subsections;
+    /** Whether this section is numbered when rendered; null means inherit from parent context. */
+    numbered;
+    /** Whether bullet points are rendered as a numbered list. */
+    numberedBullets;
+    /**
+     * Creates a new PomSection.
+     * @param opts - Optional section configuration.
+     */
+    constructor(opts) {
+        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) {
+        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() {
+        const data = {};
+        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 = []) {
+        const lines = [];
+        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;
+            let nextLevel;
+            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 {
+    sections = [];
+    sectionMap = 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, opts) {
+        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, opts) {
+        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, title, opts) {
+        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) {
+        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) {
+        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) {
+        const recurse = (sections) => {
+            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() {
+        return this.sections.map((s) => s.toDict());
+    }
+    /**
+     * Renders all sections as a combined Markdown string.
+     * @returns The complete rendered Markdown prompt text.
+     */
+    renderMarkdown() {
+        const anyNumbered = this.sections.some((s) => s.numbered);
+        const parts = [];
+        let counter = 0;
+        for (const section of this.sections) {
+            let sectionNumber = [];
+            if (section.title !== null) {
+                counter++;
+                if (anyNumbered && section.numbered !== false) {
+                    sectionNumber = [counter];
+                }
+            }
+            parts.push(section.renderMarkdown(2, sectionNumber));
+        }
+        return parts.join('\n');
+    }
+}
+//# sourceMappingURL=PomBuilder.js.map

package/dist/PomBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PomBuilder.js","sourceRoot":"","sources":["../src/PomBuilder.ts"],"names":[],"mappings":"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"}

package/dist/PromptManager.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 declare class PromptManager {
+    private rawText;
+    private postPrompt;
+    private pom;
+    private usePom;
+    /**
+     * Creates a new PromptManager.
+     * @param usePom - Whether to use structured POM sections (default true).
+     */
+    constructor(usePom?: boolean);
+    /**
+     * Sets the raw prompt text, bypassing POM rendering.
+     * @param text - The raw prompt string.
+     */
+    setPromptText(text: string): void;
+    /**
+     * Sets the post-prompt text appended after the main prompt.
+     * @param text - The post-prompt string.
+     */
+    setPostPrompt(text: string): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Returns the post-prompt text.
+     * @returns The post-prompt string, or null if not set.
+     */
+    getPostPrompt(): string | null;
+    /**
+     * Returns the underlying PomBuilder instance, if POM mode is active.
+     * @returns The PomBuilder, or null if POM is not in use.
+     */
+    getPomBuilder(): PomBuilder | null;
+}