signalwire-agents 0.1.0

package/dist/ConfigLoader.js

@@ -0,0 +1,150 @@
+/**
+ * ConfigLoader - JSON config file loader with env var interpolation.
+ *
+ * Supports ${VAR|default} syntax for env var substitution and
+ * dot-notation access for nested values.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+const ENV_VAR_PATTERN = /\$\{([^}|]+)(?:\|([^}]*))?\}/g;
+/** JSON configuration file loader with environment variable interpolation and dot-notation access. */
+export class ConfigLoader {
+    data = {};
+    filePath = null;
+    /**
+     * Create a new ConfigLoader, optionally loading a JSON file immediately.
+     * @param filePath - Path to a JSON config file to load on construction.
+     */
+    constructor(filePath) {
+        if (filePath) {
+            this.load(filePath);
+        }
+    }
+    /**
+     * Load configuration from a JSON file, performing `${VAR|default}` env var interpolation on the raw text.
+     * @param filePath - Path to the JSON config file.
+     * @returns This instance for chaining.
+     */
+    load(filePath) {
+        const absPath = resolve(filePath);
+        if (!existsSync(absPath)) {
+            throw new Error(`Config file not found: ${absPath}`);
+        }
+        const raw = readFileSync(absPath, 'utf-8');
+        const interpolated = this.interpolateEnvVars(raw);
+        this.data = JSON.parse(interpolated);
+        this.filePath = absPath;
+        return this;
+    }
+    /**
+     * Search for a config file in standard locations (CWD, `./config`, `$HOME/.signalwire`).
+     * @param filename - The config file name to search for.
+     * @returns A loaded ConfigLoader if found, or null if the file does not exist in any search path.
+     */
+    static search(filename) {
+        const searchPaths = [
+            process.cwd(),
+            join(process.cwd(), 'config'),
+            join(process.env['HOME'] ?? '', '.signalwire'),
+        ];
+        for (const dir of searchPaths) {
+            const filePath = join(dir, filename);
+            if (existsSync(filePath)) {
+                return new ConfigLoader(filePath);
+            }
+        }
+        return null;
+    }
+    /**
+     * Retrieve a configuration value using a dot-notation path (e.g. `'server.port'`).
+     * @param path - Dot-separated key path into the config object.
+     * @param defaultValue - Value returned when the path does not exist.
+     * @returns The resolved value, or defaultValue if not found.
+     */
+    get(path, defaultValue) {
+        const parts = path.split('.');
+        let current = this.data;
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return defaultValue;
+            }
+            current = current[part];
+        }
+        return (current !== undefined ? current : defaultValue);
+    }
+    /**
+     * Set a configuration value at the given dot-notation path, creating intermediate objects as needed.
+     * @param path - Dot-separated key path into the config object.
+     * @param value - The value to store.
+     * @returns This instance for chaining.
+     */
+    set(path, value) {
+        const parts = path.split('.');
+        let current = this.data;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i];
+            if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+                current[part] = {};
+            }
+            current = current[part];
+        }
+        current[parts[parts.length - 1]] = value;
+        return this;
+    }
+    /**
+     * Check whether a dot-notation path exists in the loaded configuration.
+     * @param path - Dot-separated key path to check.
+     * @returns True if the path resolves to a defined value.
+     */
+    has(path) {
+        const parts = path.split('.');
+        let current = this.data;
+        for (const part of parts) {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return false;
+            }
+            if (!(part in current))
+                return false;
+            current = current[part];
+        }
+        return true;
+    }
+    /**
+     * Return a shallow copy of the entire configuration object.
+     * @returns A copy of the top-level config data.
+     */
+    getAll() {
+        return { ...this.data };
+    }
+    /**
+     * Return the absolute path of the loaded config file, if any.
+     * @returns The file path, or null if config was loaded from an object.
+     */
+    getFilePath() {
+        return this.filePath;
+    }
+    /**
+     * Load configuration from a plain object instead of a file, useful for testing or programmatic setup.
+     * @param obj - The configuration object to use.
+     * @returns This instance for chaining.
+     */
+    loadFromObject(obj) {
+        this.data = { ...obj };
+        this.filePath = null;
+        return this;
+    }
+    /**
+     * Interpolate ${VAR|default} patterns in a string.
+     */
+    interpolateEnvVars(input) {
+        return input.replace(ENV_VAR_PATTERN, (_match, varName, defaultValue) => {
+            const envVal = process.env[varName.trim()];
+            if (envVal !== undefined)
+                return envVal;
+            if (defaultValue !== undefined)
+                return defaultValue;
+            return '';
+        });
+    }
+}
+//# sourceMappingURL=ConfigLoader.js.map

package/dist/ConfigLoader.js.map

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

package/dist/ContextBuilder.d.ts

@@ -0,0 +1,431 @@
+/**
+ * ContextBuilder - Contexts and Steps workflow system.
+ *
+ * Contexts contain ordered Steps, each with prompt text/POM sections,
+ * completion criteria, function restrictions, and navigation rules.
+ */
+/** Represents a single question within a gather operation. */
+export declare class GatherQuestion {
+    /** Unique key used to store the answer. */
+    key: string;
+    /** The question text presented to the user. */
+    question: string;
+    /** Expected answer type (e.g., "string", "number"). */
+    type: string;
+    /** Whether the answer requires user confirmation. */
+    confirm: boolean;
+    /** Optional additional prompt context for this question. */
+    prompt?: string;
+    /** Optional list of SWAIG function names available during this question. */
+    functions?: string[];
+    /**
+     * Creates a new GatherQuestion.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     */
+    constructor(opts: {
+        key: string;
+        question: string;
+        type?: string;
+        confirm?: boolean;
+        prompt?: string;
+        functions?: string[];
+    });
+    /**
+     * Serializes this question to a plain object for SWML output.
+     * @returns A dictionary representation of this question.
+     */
+    toDict(): Record<string, unknown>;
+}
+/** Collects structured information from the user through a series of questions. */
+export declare class GatherInfo {
+    private questions;
+    private outputKey?;
+    private completionAction?;
+    private prompt?;
+    /**
+     * Creates a new GatherInfo.
+     * @param opts - Optional output key, completion action, and prompt configuration.
+     */
+    constructor(opts?: {
+        outputKey?: string;
+        completionAction?: string;
+        prompt?: string;
+    });
+    /**
+     * Adds a question to this gather operation.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     * @returns This GatherInfo for chaining.
+     */
+    addQuestion(opts: {
+        key: string;
+        question: string;
+        type?: string;
+        confirm?: boolean;
+        prompt?: string;
+        functions?: string[];
+    }): this;
+    /**
+     * Returns all questions in this gather operation.
+     * @returns The array of GatherQuestion instances.
+     */
+    getQuestions(): GatherQuestion[];
+    /**
+     * Serializes this gather operation to a plain object for SWML output.
+     * @returns A dictionary representation of the gather info and its questions.
+     */
+    toDict(): Record<string, unknown>;
+}
+/** A single step within a context, with prompt content, criteria, function restrictions, and navigation rules. */
+export declare class Step {
+    /** The unique name identifying this step within its context. */
+    name: string;
+    private text;
+    private stepCriteria;
+    private functions;
+    private validSteps;
+    private validContexts;
+    private sections;
+    private gatherInfo;
+    private _end;
+    private skipUserTurn;
+    private _skipToNextStep;
+    private resetSystemPrompt;
+    private resetUserPrompt;
+    private resetConsolidate;
+    private resetFullReset;
+    /**
+     * Creates a new Step.
+     * @param name - The unique step name.
+     */
+    constructor(name: string);
+    /**
+     * Sets raw text content for this step, mutually exclusive with POM sections.
+     * @param text - The raw prompt text.
+     * @returns This step for chaining.
+     */
+    setText(text: string): this;
+    /**
+     * Adds a POM section with a body, mutually exclusive with raw text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This step for chaining.
+     */
+    addSection(title: string, body: string): this;
+    /**
+     * Adds a POM section with bullet points, mutually exclusive with raw text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This step for chaining.
+     */
+    addBullets(title: string, bullets: string[]): this;
+    /**
+     * Sets the criteria that must be met before this step is considered complete.
+     * @param criteria - A description of the completion criteria.
+     * @returns This step for chaining.
+     */
+    setStepCriteria(criteria: string): this;
+    /**
+     * Restricts which SWAIG functions are available during this step.
+     * @param functions - A function name, list of names, or "*" for all.
+     * @returns This step for chaining.
+     */
+    setFunctions(functions: string | string[]): this;
+    /**
+     * Sets which steps the AI may navigate to from this step.
+     * @param steps - List of allowed step names.
+     * @returns This step for chaining.
+     */
+    setValidSteps(steps: string[]): this;
+    /**
+     * Sets which contexts the AI may navigate to from this step.
+     * @param contexts - List of allowed context names.
+     * @returns This step for chaining.
+     */
+    setValidContexts(contexts: string[]): this;
+    /**
+     * Marks this step as an end step, terminating the conversation when reached.
+     * @param end - Whether this is an end step.
+     * @returns This step for chaining.
+     */
+    setEnd(end: boolean): this;
+    /**
+     * Sets whether to skip waiting for user input when entering this step.
+     * @param skip - Whether to skip the user turn.
+     * @returns This step for chaining.
+     */
+    setSkipUserTurn(skip: boolean): this;
+    /**
+     * Sets whether to automatically advance to the next step after this one completes.
+     * @param skip - Whether to skip to the next step.
+     * @returns This step for chaining.
+     */
+    setSkipToNextStep(skip: boolean): this;
+    /**
+     * Initializes a gather info operation on this step for collecting structured data.
+     * @param opts - Optional output key, completion action, and prompt configuration.
+     * @returns This step for chaining.
+     */
+    setGatherInfo(opts?: {
+        outputKey?: string;
+        completionAction?: string;
+        prompt?: string;
+    }): this;
+    /**
+     * Adds a question to this step's gather info operation.
+     * @param opts - Question configuration including key, question text, and optional type/confirm/prompt/functions.
+     * @returns This step for chaining.
+     */
+    addGatherQuestion(opts: {
+        key: string;
+        question: string;
+        type?: string;
+        confirm?: boolean;
+        prompt?: string;
+        functions?: string[];
+    }): this;
+    /**
+     * Removes all POM sections and raw text from this step.
+     * @returns This step for chaining.
+     */
+    clearSections(): this;
+    /**
+     * Sets the system prompt to use when resetting context at this step.
+     * @param systemPrompt - The replacement system prompt text.
+     * @returns This step for chaining.
+     */
+    setResetSystemPrompt(systemPrompt: string): this;
+    /**
+     * Sets the user prompt to use when resetting context at this step.
+     * @param userPrompt - The replacement user prompt text.
+     * @returns This step for chaining.
+     */
+    setResetUserPrompt(userPrompt: string): this;
+    /**
+     * Sets whether to consolidate conversation history when resetting at this step.
+     * @param consolidate - Whether to consolidate.
+     * @returns This step for chaining.
+     */
+    setResetConsolidate(consolidate: boolean): this;
+    /**
+     * Sets whether to perform a full conversation reset at this step.
+     * @param fullReset - Whether to fully reset.
+     * @returns This step for chaining.
+     */
+    setResetFullReset(fullReset: boolean): this;
+    private renderText;
+    /**
+     * Serializes this step to a plain object for SWML output.
+     * @returns A dictionary representation of this step.
+     */
+    toDict(): Record<string, unknown>;
+}
+/** A named context containing ordered steps, prompt configuration, and navigation rules. */
+export declare class Context {
+    /** The unique name identifying this context. */
+    name: string;
+    private steps;
+    private stepOrder;
+    private _validContexts;
+    private _validSteps;
+    private _postPrompt;
+    private _systemPrompt;
+    private systemPromptSections;
+    private _consolidate;
+    private _fullReset;
+    private _userPrompt;
+    private _isolated;
+    private promptText;
+    private promptSections;
+    private _enterFillers;
+    private _exitFillers;
+    /**
+     * Creates a new Context.
+     * @param name - The unique context name.
+     */
+    constructor(name: string);
+    /**
+     * Adds a new step to this context.
+     * @param name - The unique step name within this context.
+     * @param opts - Optional shorthand for task text, bullets, criteria, functions, and valid steps.
+     * @returns The newly created Step for further configuration.
+     */
+    addStep(name: string, opts?: {
+        task?: string;
+        bullets?: string[];
+        criteria?: string;
+        functions?: string | string[];
+        validSteps?: string[];
+    }): Step;
+    /**
+     * Returns a step by name.
+     * @param name - The step name to retrieve.
+     * @returns The matching Step, or undefined if not found.
+     */
+    getStep(name: string): Step | undefined;
+    /**
+     * Removes a step from this context by name.
+     * @param name - The step name to remove.
+     * @returns This context for chaining.
+     */
+    removeStep(name: string): this;
+    /**
+     * Moves a step to a new position in the step order.
+     * @param name - The step name to move.
+     * @param position - The zero-based index to insert at.
+     * @returns This context for chaining.
+     */
+    moveStep(name: string, position: number): this;
+    /**
+     * Sets which contexts the AI may navigate to from this context.
+     * @param contexts - List of allowed context names.
+     * @returns This context for chaining.
+     */
+    setValidContexts(contexts: string[]): this;
+    /**
+     * Sets which steps the AI may navigate to from this context.
+     * @param steps - List of allowed step names.
+     * @returns This context for chaining.
+     */
+    setValidSteps(steps: string[]): this;
+    /**
+     * Sets the post-prompt text for this context.
+     * @param postPrompt - The post-prompt string.
+     * @returns This context for chaining.
+     */
+    setPostPrompt(postPrompt: string): this;
+    /**
+     * Sets raw system prompt text, mutually exclusive with system POM sections.
+     * @param systemPrompt - The system prompt string.
+     * @returns This context for chaining.
+     */
+    setSystemPrompt(systemPrompt: string): this;
+    /**
+     * Sets whether to consolidate conversation history when entering this context.
+     * @param consolidate - Whether to consolidate.
+     * @returns This context for chaining.
+     */
+    setConsolidate(consolidate: boolean): this;
+    /**
+     * Sets whether to fully reset conversation history when entering this context.
+     * @param fullReset - Whether to fully reset.
+     * @returns This context for chaining.
+     */
+    setFullReset(fullReset: boolean): this;
+    /**
+     * Sets the user prompt text for this context.
+     * @param userPrompt - The user prompt string.
+     * @returns This context for chaining.
+     */
+    setUserPrompt(userPrompt: string): this;
+    /**
+     * Sets whether this context is isolated from other contexts' conversation history.
+     * @param isolated - Whether to isolate.
+     * @returns This context for chaining.
+     */
+    setIsolated(isolated: boolean): this;
+    /**
+     * Adds a POM section to the system prompt, mutually exclusive with raw system prompt text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This context for chaining.
+     */
+    addSystemSection(title: string, body: string): this;
+    /**
+     * Adds a POM section with bullets to the system prompt, mutually exclusive with raw system prompt text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This context for chaining.
+     */
+    addSystemBullets(title: string, bullets: string[]): this;
+    /**
+     * Sets raw prompt text for this context, mutually exclusive with POM prompt sections.
+     * @param prompt - The prompt string.
+     * @returns This context for chaining.
+     */
+    setPrompt(prompt: string): this;
+    /**
+     * Adds a POM section with a body to the context prompt, mutually exclusive with raw prompt text.
+     * @param title - The section heading.
+     * @param body - The section body text.
+     * @returns This context for chaining.
+     */
+    addSection(title: string, body: string): this;
+    /**
+     * Adds a POM section with bullets to the context prompt, mutually exclusive with raw prompt text.
+     * @param title - The section heading.
+     * @param bullets - The list of bullet point strings.
+     * @returns This context for chaining.
+     */
+    addBullets(title: string, bullets: string[]): this;
+    /**
+     * Sets filler phrases spoken when entering this context, keyed by language code.
+     * @param fillers - Map of language codes to arrays of filler phrases.
+     * @returns This context for chaining.
+     */
+    setEnterFillers(fillers: Record<string, string[]>): this;
+    /**
+     * Sets filler phrases spoken when exiting this context, keyed by language code.
+     * @param fillers - Map of language codes to arrays of filler phrases.
+     * @returns This context for chaining.
+     */
+    setExitFillers(fillers: Record<string, string[]>): this;
+    /**
+     * Adds enter filler phrases for a specific language.
+     * @param languageCode - The language code (e.g., "en-US").
+     * @param fillers - Array of filler phrases.
+     * @returns This context for chaining.
+     */
+    addEnterFiller(languageCode: string, fillers: string[]): this;
+    /**
+     * Adds exit filler phrases for a specific language.
+     * @param languageCode - The language code (e.g., "en-US").
+     * @param fillers - Array of filler phrases.
+     * @returns This context for chaining.
+     */
+    addExitFiller(languageCode: string, fillers: string[]): this;
+    /** @internal */
+    getSteps(): Map<string, Step>;
+    /** @internal */
+    getValidContexts(): string[] | null;
+    private renderPrompt;
+    private renderSystemPrompt;
+    private renderSections;
+    /**
+     * Serializes this context and all its steps to a plain object for SWML output.
+     * @returns A dictionary representation of this context.
+     */
+    toDict(): Record<string, unknown>;
+}
+/** Builds and validates a collection of named contexts for multi-step AI workflows. */
+export declare class ContextBuilder {
+    private contexts;
+    private contextOrder;
+    /**
+     * Adds a new named context to the builder.
+     * @param name - The unique context name.
+     * @returns The newly created Context for further configuration.
+     */
+    addContext(name: string): Context;
+    /**
+     * Returns a context by name.
+     * @param name - The context name to retrieve.
+     * @returns The matching Context, or undefined if not found.
+     */
+    getContext(name: string): Context | undefined;
+    /**
+     * Validates that all contexts have steps, naming constraints are met, and cross-context references are valid.
+     * @throws Error if validation fails.
+     */
+    validate(): void;
+    /**
+     * Validates and serializes all contexts to a plain object for SWML output.
+     * @returns A dictionary mapping context names to their serialized representations.
+     */
+    toDict(): Record<string, unknown>;
+}
+/**
+ * Creates a standalone Context instance without a ContextBuilder.
+ * @param name - The context name (defaults to "default").
+ * @returns A new Context instance.
+ */
+export declare function createSimpleContext(name?: string): Context;