signalwire-agents 0.1.0

package/dist/PromptManager.js

@@ -0,0 +1,108 @@
+/**
+ * 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 {
+    rawText = null;
+    postPrompt = null;
+    pom = null;
+    usePom;
+    /**
+     * 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) {
+        this.rawText = text;
+    }
+    /**
+     * Sets the post-prompt text appended after the main prompt.
+     * @param text - The post-prompt string.
+     */
+    setPostPrompt(text) {
+        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, opts) {
+        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, opts) {
+        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, title, opts) {
+        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) {
+        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() {
+        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() {
+        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() {
+        return this.pom;
+    }
+}
+//# sourceMappingURL=PromptManager.js.map

package/dist/PromptManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PromptManager.js","sourceRoot":"","sources":["../src/PromptManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,4FAA4F;AAC5F,MAAM,OAAO,aAAa;IAChB,OAAO,GAAkB,IAAI,CAAC;IAC9B,UAAU,GAAkB,IAAI,CAAC;IACjC,GAAG,GAAsB,IAAI,CAAC;IAC9B,MAAM,CAAU;IAExB;;;OAGG;IACH,YAAY,MAAM,GAAG,IAAI;QACvB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;QAC9B,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,IAAY;QACxB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,IAAY;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,UAAU,CACR,KAAa,EACb,IAMC;QAED,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,YAAY,CACV,KAAa,EACb,IAA6D;QAE7D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,aAAa,CACX,WAAmB,EACnB,KAAa,EACb,IAA4C;QAE5C,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;YACd,IAAI,CAAC,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IACnD,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,IAAI,IAAI,CAAC,OAAO,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,OAAO,CAAC;QAC/C,IAAI,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;CACF"}

package/dist/SchemaUtils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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[];
+}
+/** Validates SWML documents against structural rules with an LRU-style result cache. */
+export declare class SchemaUtils {
+    private skipValidation;
+    private cache;
+    private maxCacheSize;
+    /**
+     * Create a SchemaUtils instance.
+     * @param opts - Optional settings for skipping validation or limiting cache size.
+     */
+    constructor(opts?: {
+        skipValidation?: boolean;
+        maxCacheSize?: number;
+    });
+    /**
+     * 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;
+    private validateAiVerb;
+    /** Clear the validation cache */
+    clearCache(): void;
+    /**
+     * Get the number of cached validation results.
+     * @returns The current cache entry count.
+     */
+    getCacheSize(): number;
+    private cacheResult;
+}

package/dist/SchemaUtils.js

@@ -0,0 +1,148 @@
+/**
+ * SchemaUtils - JSON Schema validation for SWML documents.
+ *
+ * Provides basic structural validation of rendered SWML.
+ * Set SWML_SKIP_SCHEMA_VALIDATION=true to disable.
+ */
+// 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 {
+    skipValidation;
+    cache = new Map();
+    maxCacheSize;
+    /**
+     * Create a SchemaUtils instance.
+     * @param opts - Optional settings for skipping validation or limiting cache size.
+     */
+    constructor(opts) {
+        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) {
+        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 = [];
+        let doc;
+        try {
+            doc = typeof swml === 'string' ? JSON.parse(swml) : swml;
+        }
+        catch {
+            const result = { 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'])) {
+            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'];
+                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'];
+            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['ai'], errors);
+                    }
+                }
+            }
+        }
+        const result = {
+            valid: errors.length === 0,
+            errors,
+        };
+        this.cacheResult(swmlStr, result);
+        return result;
+    }
+    validateAiVerb(ai, errors) {
+        if (!ai)
+            return;
+        // Prompt must have text
+        if (ai['prompt']) {
+            const prompt = ai['prompt'];
+            if (typeof prompt === 'object' && !prompt['text']) {
+                errors.push('AI prompt must have a "text" field');
+            }
+        }
+        // SWAIG validation
+        if (ai['SWAIG']) {
+            const swaig = ai['SWAIG'];
+            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'].length; i++) {
+                    const fn = swaig['functions'][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'];
+            if (typeof pp === 'object' && !pp['text']) {
+                errors.push('AI post_prompt must have a "text" field');
+            }
+        }
+    }
+    /** Clear the validation cache */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get the number of cached validation results.
+     * @returns The current cache entry count.
+     */
+    getCacheSize() {
+        return this.cache.size;
+    }
+    cacheResult(key, result) {
+        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);
+    }
+}
+//# sourceMappingURL=SchemaUtils.js.map

package/dist/SchemaUtils.js.map

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

package/dist/ServerlessAdapter.d.ts

@@ -0,0 +1,100 @@
+/**
+ * ServerlessAdapter - Adapts AgentBase for serverless platforms.
+ *
+ * Supports AWS Lambda, Google Cloud Functions, Azure Functions, and CGI mode.
+ * Auto-detects platform from environment variables.
+ */
+/** Supported serverless platform identifiers, or 'auto' for environment-based detection. */
+export type ServerlessPlatform = 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto';
+/** Normalized incoming event from a serverless platform. */
+export interface ServerlessEvent {
+    /** HTTP method (AWS Lambda style). */
+    httpMethod?: string;
+    /** HTTP method (GCF/Azure style). */
+    method?: string;
+    /** Request headers as key-value pairs. */
+    headers?: Record<string, string>;
+    /** Request body, either raw JSON string or parsed object. */
+    body?: string | Record<string, unknown>;
+    /** Request path. */
+    path?: string;
+    /** Raw request path (AWS API Gateway v2). */
+    rawPath?: string;
+    /** Query string parameters as key-value pairs. */
+    queryStringParameters?: Record<string, string>;
+    /** Platform-specific request context metadata. */
+    requestContext?: Record<string, unknown>;
+}
+/** Normalized outgoing response returned to a serverless platform. */
+export interface ServerlessResponse {
+    /** HTTP status code. */
+    statusCode: number;
+    /** Response headers as key-value pairs. */
+    headers: Record<string, string>;
+    /** Response body as a string. */
+    body: string;
+}
+/** Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI. */
+export declare class ServerlessAdapter {
+    private platform;
+    /**
+     * Create a ServerlessAdapter for the given platform.
+     * @param platform - Target platform; defaults to 'auto' which detects from environment variables.
+     */
+    constructor(platform?: ServerlessPlatform);
+    /**
+     * Detect the serverless platform by inspecting well-known environment variables.
+     * @returns The detected platform identifier; defaults to 'lambda' if no match is found.
+     */
+    detectPlatform(): ServerlessPlatform;
+    /**
+     * Get the resolved platform identifier.
+     * @returns The serverless platform this adapter is configured for.
+     */
+    getPlatform(): ServerlessPlatform;
+    /**
+     * Convert a serverless event into a standard Request, route it through the Hono app, and return a normalized response.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @param event - The incoming serverless event to process.
+     * @returns The normalized serverless response.
+     */
+    handleRequest(app: {
+        fetch: (req: Request) => Promise<Response>;
+    }, event: ServerlessEvent): Promise<ServerlessResponse>;
+    /**
+     * Generate the platform-specific invocation URL for a deployed function.
+     * @param opts - Optional overrides for region, project, function name, stage, or API ID.
+     * @returns The constructed URL string.
+     */
+    generateUrl(opts?: {
+        region?: string;
+        projectId?: string;
+        functionName?: string;
+        stage?: string;
+        apiId?: string;
+    }): string;
+    /**
+     * Create an AWS Lambda-compatible handler function from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts a Lambda event and returns a promise of a serverless response.
+     */
+    static createLambdaHandler(app: {
+        fetch: (req: Request) => Promise<Response>;
+    }): (event: ServerlessEvent) => Promise<ServerlessResponse>;
+    /**
+     * Create a Google Cloud Functions-compatible handler from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts GCF request/response objects.
+     */
+    static createGcfHandler(app: {
+        fetch: (req: Request) => Promise<Response>;
+    }): (req: any, res: any) => Promise<void>;
+    /**
+     * Create an Azure Functions-compatible handler from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts an Azure context and request object.
+     */
+    static createAzureHandler(app: {
+        fetch: (req: Request) => Promise<Response>;
+    }): (context: any, req: any) => Promise<void>;
+}

package/dist/ServerlessAdapter.js

@@ -0,0 +1,166 @@
+/**
+ * ServerlessAdapter - Adapts AgentBase for serverless platforms.
+ *
+ * Supports AWS Lambda, Google Cloud Functions, Azure Functions, and CGI mode.
+ * Auto-detects platform from environment variables.
+ */
+import { getLogger } from './Logger.js';
+const log = getLogger('ServerlessAdapter');
+/** Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI. */
+export class ServerlessAdapter {
+    platform;
+    /**
+     * Create a ServerlessAdapter for the given platform.
+     * @param platform - Target platform; defaults to 'auto' which detects from environment variables.
+     */
+    constructor(platform = 'auto') {
+        this.platform = platform === 'auto' ? this.detectPlatform() : platform;
+    }
+    /**
+     * Detect the serverless platform by inspecting well-known environment variables.
+     * @returns The detected platform identifier; defaults to 'lambda' if no match is found.
+     */
+    detectPlatform() {
+        if (process.env['AWS_LAMBDA_FUNCTION_NAME'] || process.env['_HANDLER'])
+            return 'lambda';
+        if (process.env['FUNCTION_TARGET'] || process.env['K_SERVICE'])
+            return 'gcf';
+        if (process.env['FUNCTIONS_WORKER_RUNTIME'] || process.env['AZURE_FUNCTIONS_ENVIRONMENT'])
+            return 'azure';
+        if (process.env['GATEWAY_INTERFACE'])
+            return 'cgi';
+        return 'lambda'; // default fallback
+    }
+    /**
+     * Get the resolved platform identifier.
+     * @returns The serverless platform this adapter is configured for.
+     */
+    getPlatform() {
+        return this.platform;
+    }
+    /**
+     * Convert a serverless event into a standard Request, route it through the Hono app, and return a normalized response.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @param event - The incoming serverless event to process.
+     * @returns The normalized serverless response.
+     */
+    async handleRequest(app, event) {
+        const method = event.httpMethod ?? event.method ?? 'POST';
+        const path = event.rawPath ?? event.path ?? '/';
+        const headers = event.headers ?? {};
+        // Build URL
+        const host = headers['host'] ?? 'localhost';
+        const proto = headers['x-forwarded-proto'] ?? 'https';
+        let url = `${proto}://${host}${path}`;
+        if (event.queryStringParameters) {
+            const qs = new URLSearchParams(event.queryStringParameters).toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        // Build body
+        let body;
+        if (event.body) {
+            body = typeof event.body === 'string' ? event.body : JSON.stringify(event.body);
+        }
+        // Create Request
+        const request = new Request(url, {
+            method,
+            headers: new Headers(headers),
+            body: method !== 'GET' && method !== 'HEAD' ? body : undefined,
+        });
+        log.debug(`Handling ${method} ${path} on ${this.platform}`);
+        // Route through Hono
+        const response = await app.fetch(request);
+        // Convert back to serverless response
+        const responseHeaders = {};
+        response.headers.forEach((v, k) => { responseHeaders[k] = v; });
+        return {
+            statusCode: response.status,
+            headers: responseHeaders,
+            body: await response.text(),
+        };
+    }
+    /**
+     * Generate the platform-specific invocation URL for a deployed function.
+     * @param opts - Optional overrides for region, project, function name, stage, or API ID.
+     * @returns The constructed URL string.
+     */
+    generateUrl(opts) {
+        const functionName = opts?.functionName ?? process.env['AWS_LAMBDA_FUNCTION_NAME'] ?? 'agent';
+        switch (this.platform) {
+            case 'lambda': {
+                const region = opts?.region ?? process.env['AWS_REGION'] ?? 'us-east-1';
+                const apiId = opts?.apiId ?? 'API_ID';
+                const stage = opts?.stage ?? 'prod';
+                return `https://${apiId}.execute-api.${region}.amazonaws.com/${stage}`;
+            }
+            case 'gcf': {
+                const project = opts?.projectId ?? process.env['GCLOUD_PROJECT'] ?? 'PROJECT';
+                const region = opts?.region ?? process.env['FUNCTION_REGION'] ?? 'us-central1';
+                return `https://${region}-${project}.cloudfunctions.net/${functionName}`;
+            }
+            case 'azure': {
+                return `https://${functionName}.azurewebsites.net/api/${functionName}`;
+            }
+            case 'cgi': {
+                return `http://localhost/cgi-bin/${functionName}`;
+            }
+            default:
+                return `https://localhost/${functionName}`;
+        }
+    }
+    /**
+     * Create an AWS Lambda-compatible handler function from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts a Lambda event and returns a promise of a serverless response.
+     */
+    static createLambdaHandler(app) {
+        const adapter = new ServerlessAdapter('lambda');
+        return (event) => adapter.handleRequest(app, event);
+    }
+    /**
+     * Create a Google Cloud Functions-compatible handler from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts GCF request/response objects.
+     */
+    static createGcfHandler(app) {
+        const adapter = new ServerlessAdapter('gcf');
+        return async (req, res) => {
+            const event = {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+                path: req.path ?? req.url,
+            };
+            const response = await adapter.handleRequest(app, event);
+            res.status(response.statusCode);
+            for (const [k, v] of Object.entries(response.headers)) {
+                res.set(k, v);
+            }
+            res.send(response.body);
+        };
+    }
+    /**
+     * Create an Azure Functions-compatible handler from a Hono app.
+     * @param app - A Hono-compatible application with a `fetch` method.
+     * @returns A function that accepts an Azure context and request object.
+     */
+    static createAzureHandler(app) {
+        const adapter = new ServerlessAdapter('azure');
+        return async (context, req) => {
+            const event = {
+                method: req.method,
+                headers: req.headers,
+                body: req.body,
+                path: req.url,
+            };
+            const response = await adapter.handleRequest(app, event);
+            context.res = {
+                status: response.statusCode,
+                headers: response.headers,
+                body: response.body,
+            };
+        };
+    }
+}
+//# sourceMappingURL=ServerlessAdapter.js.map

package/dist/ServerlessAdapter.js.map

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

package/dist/SessionManager.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+/** Stateless HMAC-SHA256 token manager for SWAIG function call authentication and per-session metadata storage. */
+export declare class SessionManager {
+    /** Token validity duration in seconds. */
+    tokenExpirySecs: number;
+    private secretKey;
+    private sessionMetadata;
+    /**
+     * 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?: number, secretKey?: string);
+    /**
+     * 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?: string): string;
+    /**
+     * 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: string, callId: string): string;
+    /**
+     * 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: string, callId: string): string;
+    /**
+     * 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: string, functionName: string, token: string): boolean;
+    /**
+     * 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: string, token: string, callId: string): boolean;
+    /**
+     * 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: string): {
+        callId: string;
+        functionName: string;
+        expiry: number;
+        nonce: string;
+        signature: string;
+        expired: boolean;
+    } | null;
+    /**
+     * Retrieve metadata associated with a session.
+     * @param sessionId - The session identifier.
+     * @returns The metadata record, or undefined if no metadata exists.
+     */
+    getSessionMetadata(sessionId: string): Record<string, unknown> | undefined;
+    /**
+     * 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: string, metadata: Record<string, unknown>): void;
+    /**
+     * Delete all metadata for a session.
+     * @param sessionId - The session identifier.
+     * @returns True if the session existed and was deleted.
+     */
+    deleteSessionMetadata(sessionId: string): boolean;
+}