@framers/agentos-ext-voice-twilio 0.1.0 → 0.1.1

package/dist/TwilioVoiceService.js

@@ -0,0 +1,233 @@
+"use strict";
+// @ts-nocheck
+/**
+ * @fileoverview Twilio REST API wrapper for voice call operations.
+ * Handles Twilio client lifecycle, call creation, TwiML generation,
+ * and webhook signature verification.
+ *
+ * @module @framers/agentos-ext-voice-twilio/TwilioVoiceService
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TwilioVoiceService = void 0;
+const agentos_1 = require("@framers/agentos");
+// ============================================================================
+// Service
+// ============================================================================
+class TwilioVoiceService {
+    constructor(config) {
+        this.client = null;
+        this.running = false;
+        this.config = config;
+    }
+    /**
+     * Initialize the Twilio client.
+     * Lazily imports the twilio SDK to avoid hard failures if it's not installed.
+     */
+    async initialize() {
+        if (this.running)
+            return;
+        try {
+            // Dynamic import so the module fails gracefully if twilio isn't available
+            const twilio = await Promise.resolve().then(() => __importStar(require('twilio')));
+            const TwilioClient = twilio.default || twilio;
+            this.client = TwilioClient(this.config.accountSid, this.config.authToken);
+        }
+        catch (err) {
+            throw new Error(`Failed to initialize Twilio client. Ensure the 'twilio' package is installed. ${err}`);
+        }
+        this.running = true;
+    }
+    /**
+     * Shutdown and release the Twilio client.
+     */
+    async shutdown() {
+        if (!this.running)
+            return;
+        this.client = null;
+        this.running = false;
+    }
+    get isRunning() {
+        return this.running;
+    }
+    // ── Call Operations ──
+    /**
+     * Create an outbound call via the Twilio REST API.
+     *
+     * @param to - E.164 destination number.
+     * @param from - E.164 caller ID number.
+     * @param url - Webhook URL Twilio will request when the call connects.
+     * @param statusCallback - URL for call status change notifications.
+     * @param twiml - Optional inline TwiML (used instead of `url` if provided).
+     * @returns The Twilio call resource.
+     */
+    async createCall(to, from, url, statusCallback, twiml) {
+        this.ensureClient();
+        const params = {
+            to,
+            from,
+            statusCallback,
+            statusCallbackEvent: ['initiated', 'ringing', 'answered', 'completed'],
+            statusCallbackMethod: 'POST',
+        };
+        // If inline TwiML is provided, use it directly; otherwise point to the webhook URL
+        if (twiml) {
+            params.twiml = twiml;
+        }
+        else {
+            params.url = url;
+        }
+        const call = await this.client.calls.create(params);
+        return call;
+    }
+    /**
+     * Update an in-progress call (e.g., to hang up or redirect).
+     *
+     * @param callSid - The Twilio Call SID to update.
+     * @param updates - Fields to update on the call.
+     */
+    async updateCall(callSid, updates) {
+        this.ensureClient();
+        await this.client.calls(callSid).update(updates);
+    }
+    // ── TwiML Generation ──
+    /**
+     * Generate TwiML for "notify" mode: speak a message and hang up.
+     *
+     * @param message - The text to speak.
+     * @param voice - Twilio TTS voice name (default: 'Polly.Joanna').
+     * @returns TwiML XML string.
+     */
+    generateNotifyTwiml(message, voice = 'Polly.Joanna') {
+        const escapedMessage = (0, agentos_1.escapeXml)(message);
+        const escapedVoice = (0, agentos_1.escapeXml)(voice);
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<Response>',
+            `  <Say voice="${escapedVoice}">${escapedMessage}</Say>`,
+            '  <Hangup/>',
+            '</Response>',
+        ].join('\n');
+    }
+    /**
+     * Generate TwiML for "conversation" mode: connect a bidirectional media stream.
+     *
+     * @param mediaStreamUrl - WebSocket URL for the media stream.
+     * @param token - Optional auth token appended as a query param.
+     * @returns TwiML XML string.
+     */
+    generateConversationTwiml(mediaStreamUrl, token) {
+        const url = token
+            ? `${mediaStreamUrl}${mediaStreamUrl.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`
+            : mediaStreamUrl;
+        const escapedUrl = (0, agentos_1.escapeXml)(url);
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<Response>',
+            '  <Connect>',
+            `    <Stream url="${escapedUrl}">`,
+            '      <Parameter name="direction" value="both"/>',
+            '    </Stream>',
+            '  </Connect>',
+            '</Response>',
+        ].join('\n');
+    }
+    // ── Webhook Verification ──
+    /**
+     * Verify a Twilio webhook signature using HMAC-SHA1.
+     *
+     * Twilio signs requests by concatenating the URL with sorted POST body params,
+     * then computing HMAC-SHA1 with the auth token. The signature is sent in the
+     * `X-Twilio-Signature` header.
+     *
+     * @param url - The full URL Twilio made the request to.
+     * @param params - The parsed POST body parameters.
+     * @param signature - The value of the X-Twilio-Signature header.
+     * @param authToken - The Twilio auth token (HMAC key).
+     * @returns Whether the signature is valid.
+     */
+    verifySignature(url, params, signature, authToken) {
+        try {
+            // Use twilio's built-in validator if available
+            const twilio = require('twilio');
+            const validateRequest = twilio.validateRequest || twilio.default?.validateRequest;
+            if (typeof validateRequest === 'function') {
+                return validateRequest(authToken, signature, url, params);
+            }
+            // Fallback: manual HMAC-SHA1 verification
+            return this.manualVerifySignature(url, params, signature, authToken);
+        }
+        catch {
+            // If twilio SDK isn't loadable synchronously, fall back to manual
+            return this.manualVerifySignature(url, params, signature, authToken);
+        }
+    }
+    /**
+     * Manual HMAC-SHA1 signature verification following Twilio's algorithm:
+     * 1. Take the full URL
+     * 2. Sort POST params by key, append key+value to URL
+     * 3. HMAC-SHA1 the result with auth token
+     * 4. Base64 encode and compare to X-Twilio-Signature
+     */
+    manualVerifySignature(url, params, signature, authToken) {
+        const crypto = require('node:crypto');
+        // Build the data string: URL + sorted params concatenated as key+value
+        let data = url;
+        const sortedKeys = Object.keys(params).sort();
+        for (const key of sortedKeys) {
+            data += key + params[key];
+        }
+        const computed = crypto
+            .createHmac('sha1', authToken)
+            .update(data, 'utf-8')
+            .digest('base64');
+        // Constant-time comparison
+        try {
+            return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signature));
+        }
+        catch {
+            // Lengths differ — not equal
+            return false;
+        }
+    }
+    // ── Private ──
+    ensureClient() {
+        if (!this.client) {
+            throw new Error('TwilioVoiceService not initialized. Call initialize() first.');
+        }
+    }
+}
+exports.TwilioVoiceService = TwilioVoiceService;
+//# sourceMappingURL=TwilioVoiceService.js.map

package/dist/TwilioVoiceService.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Twilio Voice Call Extension for AgentOS.
+ *
+ * Provides an IVoiceCallProvider implementation for Twilio, plus an ITool
+ * descriptor that lets agents make and manage phone calls programmatically.
+ *
+ * Follows the same extension-pack pattern as the Telegram channel extension.
+ *
+ * @module @framers/agentos-ext-voice-twilio
+ */
+import type { ExtensionContext, ExtensionPack } from '@framers/agentos';
+import { TwilioVoiceService } from './TwilioVoiceService';
+import { TwilioVoiceProvider } from './TwilioVoiceProvider';
+import { VoiceCallTool } from './tools/voiceCall';
+export interface TwilioVoiceOptions {
+    /** Twilio Account SID. */
+    accountSid?: string;
+    /** Twilio Auth Token. */
+    authToken?: string;
+    /** Default E.164 "from" phone number. */
+    fromNumber?: string;
+    /** Base URL for webhook callbacks (e.g., https://yourdomain.com). */
+    webhookBaseUrl?: string;
+    /** Env var name for account SID (default: TWILIO_ACCOUNT_SID). */
+    accountSidEnv?: string;
+    /** Env var name for auth token (default: TWILIO_AUTH_TOKEN). */
+    authTokenEnv?: string;
+    /** Env var name for from number (default: TWILIO_FROM_NUMBER). */
+    fromNumberEnv?: string;
+    /** Extension descriptor priority (default: 50). */
+    priority?: number;
+    /** Secrets map passed from registry. */
+    secrets?: Record<string, string>;
+}
+export declare function createExtensionPack(context: ExtensionContext): ExtensionPack;
+export { TwilioVoiceService, TwilioVoiceProvider, VoiceCallTool };
+export type { TwilioServiceConfig } from './TwilioVoiceService';
+export type { VoiceCallToolHandler } from './tools/voiceCall';
+export default createExtensionPack;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAwB,MAAM,kBAAkB,CAAC;AAC9F,OAAO,EAAE,kBAAkB,EAA4B,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAA6B,MAAM,mBAAmB,CAAC;AAM7E,MAAM,WAAW,kBAAkB;IACjC,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAoCD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAmF5E;AAsCD,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,aAAa,EAAE,CAAC;AAClE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,eAAe,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,126 @@
+"use strict";
+// @ts-nocheck
+/**
+ * @fileoverview Twilio Voice Call Extension for AgentOS.
+ *
+ * Provides an IVoiceCallProvider implementation for Twilio, plus an ITool
+ * descriptor that lets agents make and manage phone calls programmatically.
+ *
+ * Follows the same extension-pack pattern as the Telegram channel extension.
+ *
+ * @module @framers/agentos-ext-voice-twilio
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceCallTool = exports.TwilioVoiceProvider = exports.TwilioVoiceService = void 0;
+exports.createExtensionPack = createExtensionPack;
+const TwilioVoiceService_1 = require("./TwilioVoiceService");
+Object.defineProperty(exports, "TwilioVoiceService", { enumerable: true, get: function () { return TwilioVoiceService_1.TwilioVoiceService; } });
+const TwilioVoiceProvider_1 = require("./TwilioVoiceProvider");
+Object.defineProperty(exports, "TwilioVoiceProvider", { enumerable: true, get: function () { return TwilioVoiceProvider_1.TwilioVoiceProvider; } });
+const voiceCall_1 = require("./tools/voiceCall");
+Object.defineProperty(exports, "VoiceCallTool", { enumerable: true, get: function () { return voiceCall_1.VoiceCallTool; } });
+// ============================================================================
+// Secret Resolution
+// ============================================================================
+function resolveSecret(optionValue, secrets, secretKey, envVarOverride, defaultEnvVar, ...fallbackEnvVars) {
+    // 1. Direct option value
+    if (optionValue)
+        return optionValue;
+    // 2. Secrets map from registry
+    if (secrets?.[secretKey])
+        return secrets[secretKey];
+    // 3. Custom env var
+    const envName = envVarOverride ?? defaultEnvVar;
+    if (process.env[envName])
+        return process.env[envName];
+    // 4. Fallback env vars
+    for (const v of fallbackEnvVars) {
+        if (process.env[v])
+            return process.env[v];
+    }
+    return '';
+}
+// ============================================================================
+// Factory
+// ============================================================================
+function createExtensionPack(context) {
+    const options = (context.options ?? {});
+    const accountSid = resolveSecret(options.accountSid, options.secrets, 'twilio.accountSid', options.accountSidEnv, 'TWILIO_ACCOUNT_SID');
+    const authToken = resolveSecret(options.authToken, options.secrets, 'twilio.authToken', options.authTokenEnv, 'TWILIO_AUTH_TOKEN');
+    const fromNumber = resolveSecret(options.fromNumber, options.secrets, 'twilio.fromNumber', options.fromNumberEnv, 'TWILIO_FROM_NUMBER', 'TWILIO_PHONE_NUMBER');
+    if (!accountSid || !authToken) {
+        throw new Error('Twilio credentials not found. Provide via options.accountSid/authToken, ' +
+            'secrets["twilio.accountSid"/"twilio.authToken"], or ' +
+            'TWILIO_ACCOUNT_SID/TWILIO_AUTH_TOKEN env vars.');
+    }
+    const config = {
+        accountSid,
+        authToken,
+        fromNumber,
+        webhookBaseUrl: options.webhookBaseUrl ?? process.env['TWILIO_WEBHOOK_BASE_URL'],
+    };
+    // ── Instantiate components ──
+    const service = new TwilioVoiceService_1.TwilioVoiceService(config);
+    const provider = new TwilioVoiceProvider_1.TwilioVoiceProvider(service);
+    // The tool handler delegates to a CallManager, but since the CallManager
+    // is owned by the host application (not this extension), we provide a
+    // no-op placeholder handler that can be replaced at runtime via the
+    // exported `setToolHandler()`.
+    let activeHandler = createPlaceholderHandler();
+    const voiceCallTool = new voiceCall_1.VoiceCallTool(
+    // Proxy handler so it always uses the latest activeHandler reference
+    {
+        initiateCall: (...args) => activeHandler.initiateCall(...args),
+        speakText: (...args) => activeHandler.speakText(...args),
+        hangupCall: (...args) => activeHandler.hangupCall(...args),
+        getCallStatus: (...args) => activeHandler.getCallStatus(...args),
+        getActiveCalls: () => activeHandler.getActiveCalls(),
+    });
+    const priority = options.priority ?? 50;
+    return {
+        name: '@framers/agentos-ext-voice-twilio',
+        version: '0.1.0',
+        descriptors: [
+            { id: 'twilioVoiceCall', kind: 'tool', priority, payload: voiceCallTool },
+            { id: 'twilioVoiceProvider', kind: 'voice-provider', priority, payload: provider },
+        ],
+        onActivate: async () => {
+            await service.initialize();
+            context.logger?.info('[TwilioVoice] Extension activated');
+        },
+        onDeactivate: async () => {
+            await service.shutdown();
+            context.logger?.info('[TwilioVoice] Extension deactivated');
+        },
+    };
+}
+// ============================================================================
+// Placeholder Handler
+// ============================================================================
+/**
+ * Creates a placeholder VoiceCallToolHandler that returns sensible errors.
+ * The host application should replace this with a real handler backed by
+ * a CallManager instance via `setToolHandler()`.
+ */
+function createPlaceholderHandler() {
+    return {
+        async initiateCall(_toNumber, _message, _mode) {
+            throw new Error('VoiceCallToolHandler not configured. The host application must provide a handler ' +
+                'backed by a CallManager instance.');
+        },
+        speakText(_callId, _text) {
+            throw new Error('VoiceCallToolHandler not configured.');
+        },
+        async hangupCall(_callId) {
+            throw new Error('VoiceCallToolHandler not configured.');
+        },
+        getCallStatus(_callId) {
+            return undefined;
+        },
+        getActiveCalls() {
+            return [];
+        },
+    };
+}
+exports.default = createExtensionPack;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/tools/voiceCall.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @fileoverview ITool implementation for making and managing phone calls via Twilio.
+ *
+ * Provides agents with the ability to initiate calls, speak text, end calls,
+ * and query call status through a unified tool interface.
+ *
+ * @module @framers/agentos-ext-voice-twilio/tools/voiceCall
+ */
+import type { ITool, ToolExecutionContext, ToolExecutionResult, CallMode, CallRecord } from '@framers/agentos';
+/**
+ * Abstraction over call management that the tool delegates to.
+ * Typically backed by a {@link CallManager} instance, but can be mocked for testing.
+ */
+export interface VoiceCallToolHandler {
+    /** Initiate an outbound call. */
+    initiateCall(toNumber: string, message?: string, mode?: CallMode): Promise<CallRecord>;
+    /** Speak text into an active call. */
+    speakText(callId: string, text: string): void;
+    /** Hang up an active call. */
+    hangupCall(callId: string): Promise<void>;
+    /** Get the current status of a call. */
+    getCallStatus(callId: string): CallRecord | undefined;
+    /** Get all active (non-terminal) calls. */
+    getActiveCalls(): CallRecord[];
+}
+interface VoiceCallToolInput {
+    /** The action to perform. */
+    action: 'initiate_call' | 'speak' | 'end_call' | 'get_status';
+    /** E.164 phone number to call (required for initiate_call). */
+    toNumber?: string;
+    /** Message text to speak (used for initiate_call in notify mode and speak action). */
+    message?: string;
+    /** Call ID (required for speak, end_call, get_status). */
+    callId?: string;
+    /** Call mode: 'notify' for one-way TTS, 'conversation' for bidirectional. */
+    mode?: CallMode;
+}
+export declare class VoiceCallTool implements ITool<VoiceCallToolInput> {
+    private readonly handler;
+    readonly id = "twilioVoiceCall";
+    readonly name = "twilioVoiceCall";
+    readonly displayName = "Twilio Voice Call";
+    readonly description: string;
+    readonly category = "communication";
+    readonly version = "0.1.0";
+    readonly hasSideEffects = true;
+    readonly inputSchema: {
+        type: "object";
+        required: readonly ["action"];
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            toNumber: {
+                type: string;
+                description: string;
+            };
+            message: {
+                type: string;
+                description: string;
+            };
+            callId: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+    };
+    readonly outputSchema: {
+        type: "object";
+        properties: {
+            callId: {
+                type: string;
+                description: string;
+            };
+            state: {
+                type: string;
+                description: string;
+            };
+            provider: {
+                type: string;
+                description: string;
+            };
+            providerCallId: {
+                type: string;
+                description: string;
+            };
+            direction: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                description: string;
+            };
+            fromNumber: {
+                type: string;
+                description: string;
+            };
+            toNumber: {
+                type: string;
+                description: string;
+            };
+            activeCalls: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+        };
+    };
+    constructor(handler: VoiceCallToolHandler);
+    execute(args: VoiceCallToolInput, _context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    validateArgs(args: Record<string, any>): {
+        isValid: boolean;
+        errors?: string[];
+    };
+    private handleInitiateCall;
+    private handleSpeak;
+    private handleEndCall;
+    private handleGetStatus;
+}
+export {};
+//# sourceMappingURL=voiceCall.d.ts.map

package/dist/tools/voiceCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voiceCall.d.ts","sourceRoot":"","sources":["../../src/tools/voiceCall.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,oBAAoB,EACpB,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACX,MAAM,kBAAkB,CAAC;AAM1B;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACvF,sCAAsC;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,8BAA8B;IAC9B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,wCAAwC;IACxC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,2CAA2C;IAC3C,cAAc,IAAI,UAAU,EAAE,CAAC;CAChC;AAMD,UAAU,kBAAkB;IAC1B,6BAA6B;IAC7B,MAAM,EAAE,eAAe,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,CAAC;IAC9D,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAMD,qBAAa,aAAc,YAAW,KAAK,CAAC,kBAAkB,CAAC;IA4DjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IA3DpC,SAAgB,EAAE,qBAAqB;IACvC,SAAgB,IAAI,qBAAqB;IACzC,SAAgB,WAAW,uBAAuB;IAClD,SAAgB,WAAW,SAGkD;IAC7E,SAAgB,QAAQ,mBAAmB;IAC3C,SAAgB,OAAO,WAAW;IAClC,SAAgB,cAAc,QAAQ;IAEtC,SAAgB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;MA2BzB;IAEF,SAAgB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiB1B;gBAE2B,OAAO,EAAE,oBAAoB;IAEpD,OAAO,CACX,IAAI,EAAE,kBAAkB,EACxB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IA6B/B,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE;YAmClE,kBAAkB;IA0BhC,OAAO,CAAC,WAAW;YAqBL,aAAa;IAkB3B,OAAO,CAAC,eAAe;CAwCxB"}