signalwire-agents 0.1.0

package/dist/SessionManager.js

@@ -0,0 +1,155 @@
+/**
+ * SessionManager - Stateless HMAC-SHA256 token generation and validation.
+ *
+ * Tokens encode call_id, function name, expiry and a nonce, signed with a
+ * shared secret. No server-side state is stored.
+ */
+import { randomBytes, createHmac } from 'node:crypto';
+/** Stateless HMAC-SHA256 token manager for SWAIG function call authentication and per-session metadata storage. */
+export class SessionManager {
+    /** Token validity duration in seconds. */
+    tokenExpirySecs;
+    secretKey;
+    sessionMetadata = new Map();
+    /**
+     * Create a new SessionManager.
+     * @param tokenExpirySecs - Token validity duration in seconds (default 3600).
+     * @param secretKey - HMAC signing secret; a random key is generated if omitted.
+     */
+    constructor(tokenExpirySecs = 3600, secretKey) {
+        this.tokenExpirySecs = tokenExpirySecs;
+        this.secretKey = secretKey ?? randomBytes(32).toString('hex');
+    }
+    /**
+     * Return the given callId or generate a new random session identifier.
+     * @param callId - Existing call ID to reuse.
+     * @returns The call ID string.
+     */
+    createSession(callId) {
+        if (callId)
+            return callId;
+        return randomBytes(16).toString('base64url');
+    }
+    /**
+     * Generate a signed, base64url-encoded token binding a function name to a call ID.
+     * @param functionName - The SWAIG function name to bind.
+     * @param callId - The call ID to bind.
+     * @returns A base64url-encoded token string.
+     */
+    generateToken(functionName, callId) {
+        const expiry = Math.floor(Date.now() / 1000) + this.tokenExpirySecs;
+        const nonce = randomBytes(4).toString('hex');
+        const message = `${callId}:${functionName}:${expiry}:${nonce}`;
+        const signature = createHmac('sha256', this.secretKey)
+            .update(message)
+            .digest('hex')
+            .slice(0, 16);
+        const token = `${callId}.${functionName}.${expiry}.${nonce}.${signature}`;
+        return Buffer.from(token).toString('base64url');
+    }
+    /**
+     * Alias for {@link generateToken}.
+     * @param functionName - The SWAIG function name to bind.
+     * @param callId - The call ID to bind.
+     * @returns A base64url-encoded token string.
+     */
+    createToolToken(functionName, callId) {
+        return this.generateToken(functionName, callId);
+    }
+    /**
+     * Validate a token against the expected call ID and function name.
+     * @param callId - The expected call ID.
+     * @param functionName - The expected function name.
+     * @param token - The base64url-encoded token to validate.
+     * @returns True if the token is valid and not expired.
+     */
+    validateToken(callId, functionName, token) {
+        try {
+            const decoded = Buffer.from(token, 'base64url').toString();
+            const parts = decoded.split('.');
+            if (parts.length !== 5)
+                return false;
+            const [tokenCallId, tokenFunction, tokenExpiry, tokenNonce, tokenSignature] = parts;
+            const effectiveCallId = callId || tokenCallId;
+            if (tokenFunction !== functionName)
+                return false;
+            const expiry = parseInt(tokenExpiry, 10);
+            if (expiry < Date.now() / 1000)
+                return false;
+            const message = `${tokenCallId}:${tokenFunction}:${tokenExpiry}:${tokenNonce}`;
+            const expectedSig = createHmac('sha256', this.secretKey)
+                .update(message)
+                .digest('hex')
+                .slice(0, 16);
+            if (tokenSignature !== expectedSig)
+                return false;
+            if (tokenCallId !== effectiveCallId)
+                return false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Alias for {@link validateToken} with reordered parameters.
+     * @param functionName - The expected function name.
+     * @param token - The base64url-encoded token to validate.
+     * @param callId - The expected call ID.
+     * @returns True if the token is valid and not expired.
+     */
+    validateToolToken(functionName, token, callId) {
+        return this.validateToken(callId, functionName, token);
+    }
+    /**
+     * Decode token components for debugging without validating the signature.
+     * @param token - The base64url-encoded token to decode.
+     * @returns The decoded token fields and expiration status, or null if malformed.
+     */
+    debugToken(token) {
+        try {
+            const decoded = Buffer.from(token, 'base64url').toString();
+            const parts = decoded.split('.');
+            if (parts.length !== 5)
+                return null;
+            const [callId, functionName, expiryStr, nonce, signature] = parts;
+            const expiry = parseInt(expiryStr, 10);
+            return {
+                callId,
+                functionName,
+                expiry,
+                nonce,
+                signature,
+                expired: expiry < Date.now() / 1000,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Retrieve metadata associated with a session.
+     * @param sessionId - The session identifier.
+     * @returns The metadata record, or undefined if no metadata exists.
+     */
+    getSessionMetadata(sessionId) {
+        return this.sessionMetadata.get(sessionId);
+    }
+    /**
+     * Merge metadata into a session, creating the entry if it does not exist.
+     * @param sessionId - The session identifier.
+     * @param metadata - Key-value pairs to merge into the session metadata.
+     */
+    setSessionMetadata(sessionId, metadata) {
+        this.sessionMetadata.set(sessionId, { ...this.sessionMetadata.get(sessionId), ...metadata });
+    }
+    /**
+     * Delete all metadata for a session.
+     * @param sessionId - The session identifier.
+     * @returns True if the session existed and was deleted.
+     */
+    deleteSessionMetadata(sessionId) {
+        return this.sessionMetadata.delete(sessionId);
+    }
+}
+//# sourceMappingURL=SessionManager.js.map

package/dist/SessionManager.js.map

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

package/dist/SslConfig.d.ts

@@ -0,0 +1,77 @@
+/**
+ * SslConfig - SSL/TLS configuration for HTTPS serving.
+ *
+ * Env vars:
+ *   SWML_SSL_ENABLED: true|false
+ *   SWML_SSL_CERT_PATH: path to PEM cert
+ *   SWML_SSL_KEY_PATH: path to PEM key
+ *   SWML_SSL_DOMAIN: domain for HSTS
+ */
+/** Configuration options for SSL/TLS setup. */
+export interface SslOptions {
+    /** Whether SSL is enabled. */
+    enabled?: boolean;
+    /** Filesystem path to the PEM-encoded certificate. */
+    certPath?: string;
+    /** Filesystem path to the PEM-encoded private key. */
+    keyPath?: string;
+    /** Domain name used for HSTS headers. */
+    domain?: string;
+    /** Whether to send HSTS headers; defaults to true. */
+    hsts?: boolean;
+    /** HSTS max-age in seconds; defaults to 31536000 (1 year). */
+    hstsMaxAge?: number;
+}
+/** Manages SSL/TLS configuration sourced from explicit options or environment variables. */
+export declare class SslConfig {
+    /** Whether SSL is enabled. */
+    enabled: boolean;
+    /** Filesystem path to the PEM certificate, or null if unset. */
+    certPath: string | null;
+    /** Filesystem path to the PEM private key, or null if unset. */
+    keyPath: string | null;
+    /** Domain name for HSTS, or null if unset. */
+    domain: string | null;
+    /** Whether HSTS headers should be emitted. */
+    hsts: boolean;
+    /** HSTS max-age value in seconds. */
+    hstsMaxAge: number;
+    /**
+     * Create an SslConfig, falling back to environment variables for any unset options.
+     * @param opts - Optional SSL configuration overrides.
+     */
+    constructor(opts?: SslOptions);
+    /**
+     * Check whether SSL is fully configured: enabled with both cert and key files present on disk.
+     * @returns True if SSL is enabled and both certificate and key files exist.
+     */
+    isConfigured(): boolean;
+    /**
+     * Read the PEM certificate file from disk.
+     * @returns The certificate contents, or null if the file is missing.
+     */
+    getCert(): string | null;
+    /**
+     * Read the PEM private key file from disk.
+     * @returns The key contents, or null if the file is missing.
+     */
+    getKey(): string | null;
+    /**
+     * Build the Strict-Transport-Security header value.
+     * @returns The HSTS header string, or null if HSTS is disabled or SSL is off.
+     */
+    getHstsHeader(): string | null;
+    /**
+     * Create the options object needed by Node.js `https.createServer()`.
+     * @returns An object with `cert` and `key` strings, or null if either file is missing.
+     */
+    getServerOptions(): {
+        cert: string;
+        key: string;
+    } | null;
+    /**
+     * Return a Hono middleware that appends the HSTS header to every response.
+     * @returns A Hono-compatible middleware function.
+     */
+    hstsMiddleware(): (c: any, next: () => Promise<void>) => Promise<void>;
+}

package/dist/SslConfig.js

@@ -0,0 +1,100 @@
+/**
+ * SslConfig - SSL/TLS configuration for HTTPS serving.
+ *
+ * Env vars:
+ *   SWML_SSL_ENABLED: true|false
+ *   SWML_SSL_CERT_PATH: path to PEM cert
+ *   SWML_SSL_KEY_PATH: path to PEM key
+ *   SWML_SSL_DOMAIN: domain for HSTS
+ */
+import { readFileSync, existsSync } from 'node:fs';
+/** Manages SSL/TLS configuration sourced from explicit options or environment variables. */
+export class SslConfig {
+    /** Whether SSL is enabled. */
+    enabled;
+    /** Filesystem path to the PEM certificate, or null if unset. */
+    certPath;
+    /** Filesystem path to the PEM private key, or null if unset. */
+    keyPath;
+    /** Domain name for HSTS, or null if unset. */
+    domain;
+    /** Whether HSTS headers should be emitted. */
+    hsts;
+    /** HSTS max-age value in seconds. */
+    hstsMaxAge;
+    /**
+     * Create an SslConfig, falling back to environment variables for any unset options.
+     * @param opts - Optional SSL configuration overrides.
+     */
+    constructor(opts) {
+        this.enabled = opts?.enabled ?? (process.env['SWML_SSL_ENABLED'] === 'true');
+        this.certPath = opts?.certPath ?? process.env['SWML_SSL_CERT_PATH'] ?? null;
+        this.keyPath = opts?.keyPath ?? process.env['SWML_SSL_KEY_PATH'] ?? null;
+        this.domain = opts?.domain ?? process.env['SWML_SSL_DOMAIN'] ?? null;
+        this.hsts = opts?.hsts ?? true;
+        this.hstsMaxAge = opts?.hstsMaxAge ?? 31536000; // 1 year
+    }
+    /**
+     * Check whether SSL is fully configured: enabled with both cert and key files present on disk.
+     * @returns True if SSL is enabled and both certificate and key files exist.
+     */
+    isConfigured() {
+        if (!this.enabled)
+            return false;
+        if (!this.certPath || !this.keyPath)
+            return false;
+        return existsSync(this.certPath) && existsSync(this.keyPath);
+    }
+    /**
+     * Read the PEM certificate file from disk.
+     * @returns The certificate contents, or null if the file is missing.
+     */
+    getCert() {
+        if (!this.certPath || !existsSync(this.certPath))
+            return null;
+        return readFileSync(this.certPath, 'utf-8');
+    }
+    /**
+     * Read the PEM private key file from disk.
+     * @returns The key contents, or null if the file is missing.
+     */
+    getKey() {
+        if (!this.keyPath || !existsSync(this.keyPath))
+            return null;
+        return readFileSync(this.keyPath, 'utf-8');
+    }
+    /**
+     * Build the Strict-Transport-Security header value.
+     * @returns The HSTS header string, or null if HSTS is disabled or SSL is off.
+     */
+    getHstsHeader() {
+        if (!this.hsts || !this.enabled)
+            return null;
+        return `max-age=${this.hstsMaxAge}; includeSubDomains`;
+    }
+    /**
+     * Create the options object needed by Node.js `https.createServer()`.
+     * @returns An object with `cert` and `key` strings, or null if either file is missing.
+     */
+    getServerOptions() {
+        const cert = this.getCert();
+        const key = this.getKey();
+        if (!cert || !key)
+            return null;
+        return { cert, key };
+    }
+    /**
+     * Return a Hono middleware that appends the HSTS header to every response.
+     * @returns A Hono-compatible middleware function.
+     */
+    hstsMiddleware() {
+        return async (c, next) => {
+            await next();
+            const hsts = this.getHstsHeader();
+            if (hsts) {
+                c.res.headers.set('Strict-Transport-Security', hsts);
+            }
+        };
+    }
+}
+//# sourceMappingURL=SslConfig.js.map

package/dist/SslConfig.js.map

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

package/dist/SwaigFunction.d.ts

@@ -0,0 +1,88 @@
+/**
+ * SwaigFunction - Wraps a handler function with metadata for SWAIG registration.
+ */
+import { SwaigFunctionResult } from './SwaigFunctionResult.js';
+/**
+ * Handler function for a SWAIG tool invocation.
+ * @param args - Parsed arguments extracted by the AI from user speech.
+ * @param rawData - The full raw request payload from SignalWire.
+ * @returns A SwaigFunctionResult, a plain object with a response key, a string, or a Promise of any of these.
+ */
+export type SwaigHandler = (args: Record<string, unknown>, rawData: Record<string, unknown>) => SwaigFunctionResult | Record<string, unknown> | string | Promise<SwaigFunctionResult | Record<string, unknown> | string>;
+/** Configuration options for creating a SwaigFunction. */
+export interface SwaigFunctionOptions {
+    /** Unique name used to register and invoke this tool. */
+    name: string;
+    /** The handler function called when the tool is invoked. */
+    handler: SwaigHandler;
+    /** Human-readable description of what the tool does, shown to the AI. */
+    description: string;
+    /** JSON Schema properties describing the tool's parameters. */
+    parameters?: Record<string, unknown>;
+    /** Whether this tool requires session token authentication. */
+    secure?: boolean;
+    /** Language-keyed filler phrases spoken while the tool executes. */
+    fillers?: Record<string, string[]>;
+    /** Audio file URL to play while waiting for the tool to complete. */
+    waitFile?: string;
+    /** Number of times to loop the wait file. */
+    waitFileLoops?: number;
+    /** External webhook URL; makes this an externally-hosted tool. */
+    webhookUrl?: string;
+    /** List of required parameter names. */
+    required?: string[];
+    /** Additional fields to include in the SWAIG definition output. */
+    extraFields?: Record<string, unknown>;
+}
+/**
+ * Wraps a tool handler function with metadata for SWAIG registration.
+ *
+ * Manages the tool's name, description, parameter schema, and handler,
+ * and serializes the definition into the SWAIG wire format.
+ */
+export declare class SwaigFunction {
+    /** Unique name used to register and invoke this tool. */
+    name: string;
+    /** The handler function called when the tool is invoked. */
+    handler: SwaigHandler;
+    /** Human-readable description shown to the AI. */
+    description: string;
+    /** JSON Schema properties describing the tool's parameters. */
+    parameters: Record<string, unknown>;
+    /** Whether this tool requires session token authentication. */
+    secure: boolean;
+    /** Language-keyed filler phrases spoken while the tool executes. */
+    fillers?: Record<string, string[]>;
+    /** Audio file URL to play while waiting for the tool to complete. */
+    waitFile?: string;
+    /** Number of times to loop the wait file. */
+    waitFileLoops?: number;
+    /** External webhook URL; set when the tool is externally hosted. */
+    webhookUrl?: string;
+    /** List of required parameter names. */
+    required: string[];
+    /** Additional fields included in the SWAIG definition output. */
+    extraFields: Record<string, unknown>;
+    /** Whether this tool is externally hosted (has a webhookUrl). */
+    isExternal: boolean;
+    /**
+     * @param opts - Configuration options for the SWAIG function.
+     */
+    constructor(opts: SwaigFunctionOptions);
+    private ensureParameterStructure;
+    /**
+     * Invoke the handler with the given arguments and return a serialized result.
+     * @param args - Parsed arguments from the AI.
+     * @param rawData - The full raw request payload.
+     * @returns A serialized result dictionary suitable for the SWAIG response.
+     */
+    execute(args: Record<string, unknown>, rawData?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Serialize this function to the SWAIG wire format for inclusion in SWML.
+     * @param baseUrl - The base URL of the agent server.
+     * @param token - Optional session token for secure functions.
+     * @param callId - Optional call ID for secure function URLs.
+     * @returns A SWAIG function definition object.
+     */
+    toSwaig(baseUrl: string, token?: string, callId?: string): Record<string, unknown>;
+}

package/dist/SwaigFunction.js

@@ -0,0 +1,125 @@
+/**
+ * SwaigFunction - Wraps a handler function with metadata for SWAIG registration.
+ */
+import { SwaigFunctionResult } from './SwaigFunctionResult.js';
+import { getLogger } from './Logger.js';
+const log = getLogger('SwaigFunction');
+/**
+ * Wraps a tool handler function with metadata for SWAIG registration.
+ *
+ * Manages the tool's name, description, parameter schema, and handler,
+ * and serializes the definition into the SWAIG wire format.
+ */
+export class SwaigFunction {
+    /** Unique name used to register and invoke this tool. */
+    name;
+    /** The handler function called when the tool is invoked. */
+    handler;
+    /** Human-readable description shown to the AI. */
+    description;
+    /** JSON Schema properties describing the tool's parameters. */
+    parameters;
+    /** Whether this tool requires session token authentication. */
+    secure;
+    /** Language-keyed filler phrases spoken while the tool executes. */
+    fillers;
+    /** Audio file URL to play while waiting for the tool to complete. */
+    waitFile;
+    /** Number of times to loop the wait file. */
+    waitFileLoops;
+    /** External webhook URL; set when the tool is externally hosted. */
+    webhookUrl;
+    /** List of required parameter names. */
+    required;
+    /** Additional fields included in the SWAIG definition output. */
+    extraFields;
+    /** Whether this tool is externally hosted (has a webhookUrl). */
+    isExternal;
+    /**
+     * @param opts - Configuration options for the SWAIG function.
+     */
+    constructor(opts) {
+        this.name = opts.name;
+        this.handler = opts.handler;
+        this.description = opts.description;
+        this.parameters = opts.parameters ?? {};
+        this.secure = opts.secure ?? false;
+        this.fillers = opts.fillers;
+        this.waitFile = opts.waitFile;
+        this.waitFileLoops = opts.waitFileLoops;
+        this.webhookUrl = opts.webhookUrl;
+        this.required = opts.required ?? [];
+        this.extraFields = opts.extraFields ?? {};
+        this.isExternal = opts.webhookUrl !== undefined;
+    }
+    ensureParameterStructure() {
+        if (!this.parameters || Object.keys(this.parameters).length === 0) {
+            return { type: 'object', properties: {} };
+        }
+        if ('type' in this.parameters && 'properties' in this.parameters) {
+            return this.parameters;
+        }
+        const result = {
+            type: 'object',
+            properties: this.parameters,
+        };
+        if (this.required.length)
+            result['required'] = this.required;
+        return result;
+    }
+    /**
+     * Invoke the handler with the given arguments and return a serialized result.
+     * @param args - Parsed arguments from the AI.
+     * @param rawData - The full raw request payload.
+     * @returns A serialized result dictionary suitable for the SWAIG response.
+     */
+    async execute(args, rawData) {
+        try {
+            const result = await this.handler(args, rawData ?? {});
+            if (result instanceof SwaigFunctionResult) {
+                return result.toDict();
+            }
+            if (typeof result === 'object' && result !== null && 'response' in result) {
+                return result;
+            }
+            if (typeof result === 'object' && result !== null) {
+                return new SwaigFunctionResult('Function completed successfully').toDict();
+            }
+            return new SwaigFunctionResult(String(result)).toDict();
+        }
+        catch (err) {
+            log.error(`Error executing SWAIG function ${this.name}: ${err}`);
+            return new SwaigFunctionResult("Sorry, I couldn't complete that action. Please try again or contact support if the issue persists.").toDict();
+        }
+    }
+    /**
+     * Serialize this function to the SWAIG wire format for inclusion in SWML.
+     * @param baseUrl - The base URL of the agent server.
+     * @param token - Optional session token for secure functions.
+     * @param callId - Optional call ID for secure function URLs.
+     * @returns A SWAIG function definition object.
+     */
+    toSwaig(baseUrl, token, callId) {
+        let url = `${baseUrl}/swaig`;
+        if (token && callId) {
+            url = `${url}?token=${token}&call_id=${callId}`;
+        }
+        const def = {
+            function: this.name,
+            description: this.description,
+            parameters: this.ensureParameterStructure(),
+        };
+        if (url)
+            def['web_hook_url'] = url;
+        if (this.fillers && Object.keys(this.fillers).length > 0) {
+            def['fillers'] = this.fillers;
+        }
+        if (this.waitFile)
+            def['wait_file'] = this.waitFile;
+        if (this.waitFileLoops !== undefined)
+            def['wait_file_loops'] = this.waitFileLoops;
+        Object.assign(def, this.extraFields);
+        return def;
+    }
+}
+//# sourceMappingURL=SwaigFunction.js.map

package/dist/SwaigFunction.js.map

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