@framers/agentos-ext-voice-plivo 0.1.0 → 0.1.2

package/dist/PlivoVoiceService.js

@@ -0,0 +1,228 @@
+"use strict";
+// @ts-nocheck
+/**
+ * @fileoverview Wrapper around the Plivo Voice API SDK.
+ *
+ * Handles Plivo client lifecycle, call control operations (create, hangup,
+ * speak), Plivo XML generation for notify/conversation modes, and webhook
+ * signature verification.
+ *
+ * @module @framers/agentos-ext-voice-plivo/PlivoVoiceService
+ */
+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.PlivoVoiceService = void 0;
+const node_crypto_1 = require("node:crypto");
+const agentos_1 = require("@framers/agentos");
+/** Default Plivo TTS voice. */
+const DEFAULT_VOICE = 'Polly.Joanna';
+// ============================================================================
+// Service
+// ============================================================================
+class PlivoVoiceService {
+    constructor(config) {
+        this.client = null;
+        this.config = config;
+    }
+    // ── Lifecycle ──
+    /**
+     * Initialize the Plivo SDK client via dynamic import.
+     * Plivo's Node SDK is CommonJS; dynamic import avoids bundling issues.
+     */
+    async initialize() {
+        if (this.client)
+            return;
+        try {
+            const plivoModule = await Promise.resolve().then(() => __importStar(require('plivo')));
+            const Plivo = plivoModule.default ?? plivoModule;
+            this.client = new Plivo.Client(this.config.authId, this.config.authToken);
+        }
+        catch (err) {
+            throw new Error(`Failed to initialize Plivo client. Ensure the "plivo" package is installed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Gracefully shut down the service and release resources.
+     */
+    async shutdown() {
+        this.client = null;
+    }
+    /** Whether the service has been initialized. */
+    get isInitialized() {
+        return this.client !== null;
+    }
+    // ── Call Control ──
+    /**
+     * Create an outbound call via the Plivo Calls API.
+     *
+     * @param from   - E.164 caller ID.
+     * @param to     - E.164 destination number.
+     * @param answerUrl    - URL Plivo fetches when the call is answered.
+     * @param answerMethod - HTTP method for the answer URL (GET or POST).
+     * @returns The Plivo API response containing `requestUuid` (call UUID).
+     */
+    async createCall(from, to, answerUrl, answerMethod = 'POST') {
+        this.ensureInitialized();
+        const response = await this.client.calls.create(from, to, answerUrl, {
+            answerMethod,
+        });
+        return {
+            requestUuid: response.requestUuid ?? response.request_uuid,
+            apiId: response.apiId ?? response.api_id,
+            message: response.message ?? '',
+        };
+    }
+    /**
+     * Hang up an active call by its UUID.
+     *
+     * @param callUuid - The Plivo call UUID to terminate.
+     */
+    async hangupCall(callUuid) {
+        this.ensureInitialized();
+        await this.client.calls.hangup(callUuid);
+    }
+    /**
+     * Play TTS speech into an active call via the Plivo Speak API.
+     *
+     * @param callUuid - The Plivo call UUID.
+     * @param text     - Text to speak.
+     * @param voice    - Plivo voice name (default: Polly.Joanna).
+     */
+    async speakText(callUuid, text, voice) {
+        this.ensureInitialized();
+        await this.client.calls.speak(callUuid, text, {
+            voice: voice ?? DEFAULT_VOICE,
+        });
+    }
+    // ── Plivo XML Generation ──
+    /**
+     * Generate Plivo XML for "notify" mode: speak a message then hang up.
+     *
+     * @param message - The message text to speak.
+     * @param voice   - Plivo TTS voice (default: Polly.Joanna).
+     * @returns Plivo XML string.
+     *
+     * @example
+     * ```xml
+     * <?xml version="1.0" encoding="UTF-8"?>
+     * <Response>
+     *   <Speak voice="Polly.Joanna">Hello, your appointment is confirmed.</Speak>
+     *   <Hangup/>
+     * </Response>
+     * ```
+     */
+    generateNotifyXml(message, voice) {
+        const v = voice ?? DEFAULT_VOICE;
+        const escaped = (0, agentos_1.escapeXml)(message);
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<Response>',
+            `  <Speak voice="${v}">${escaped}</Speak>`,
+            '  <Hangup/>',
+            '</Response>',
+        ].join('\n');
+    }
+    /**
+     * Generate Plivo XML for "conversation" mode: speak a greeting,
+     * gather DTMF/speech input, then redirect back to the webhook URL
+     * for a multi-turn loop.
+     *
+     * @param webhookUrl - URL to redirect to after gathering input.
+     * @param greeting   - Optional greeting to speak before gathering.
+     * @param voice      - Plivo TTS voice (default: Polly.Joanna).
+     * @returns Plivo XML string.
+     *
+     * @example
+     * ```xml
+     * <?xml version="1.0" encoding="UTF-8"?>
+     * <Response>
+     *   <Speak voice="Polly.Joanna">Hello, how can I help you?</Speak>
+     *   <GetInput action="https://example.com/voice/webhook/plivo"
+     *             method="POST" inputType="speech" executionTimeout="30">
+     *     <Speak voice="Polly.Joanna">I am listening.</Speak>
+     *   </GetInput>
+     *   <Redirect method="POST">https://example.com/voice/webhook/plivo</Redirect>
+     * </Response>
+     * ```
+     */
+    generateConversationXml(webhookUrl, greeting, voice) {
+        const v = voice ?? DEFAULT_VOICE;
+        const escapedUrl = (0, agentos_1.escapeXml)(webhookUrl);
+        const lines = [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<Response>',
+        ];
+        if (greeting) {
+            lines.push(`  <Speak voice="${v}">${(0, agentos_1.escapeXml)(greeting)}</Speak>`);
+        }
+        lines.push(`  <GetInput action="${escapedUrl}" method="POST" inputType="speech" executionTimeout="30">`, `    <Speak voice="${v}">I am listening.</Speak>`, '  </GetInput>', `  <Redirect method="POST">${escapedUrl}</Redirect>`, '</Response>');
+        return lines.join('\n');
+    }
+    // ── Webhook Verification ──
+    /**
+     * Verify a Plivo webhook signature (V3 — HMAC-SHA256).
+     *
+     * Plivo V3 signatures are computed as:
+     *   HMAC-SHA256(authToken, requestUrl + nonce)
+     * and sent via the `X-Plivo-Signature-V3` header.
+     *
+     * @param url       - The full request URL (including query string).
+     * @param nonce     - The nonce from `X-Plivo-Signature-V3-Nonce` header.
+     * @param signature - The signature from `X-Plivo-Signature-V3` header.
+     * @param authToken - The Plivo auth token used as the HMAC key.
+     * @returns Whether the signature is valid.
+     */
+    verifySignature(url, nonce, signature, authToken) {
+        const expected = (0, node_crypto_1.createHmac)('sha256', authToken)
+            .update(url + nonce)
+            .digest('base64');
+        // Constant-time comparison
+        if (expected.length !== signature.length)
+            return false;
+        let mismatch = 0;
+        for (let i = 0; i < expected.length; i++) {
+            mismatch |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+        }
+        return mismatch === 0;
+    }
+    // ── Internal ──
+    ensureInitialized() {
+        if (!this.client) {
+            throw new Error('PlivoVoiceService is not initialized. Call initialize() first.');
+        }
+    }
+}
+exports.PlivoVoiceService = PlivoVoiceService;
+//# sourceMappingURL=PlivoVoiceService.js.map

package/dist/PlivoVoiceService.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Plivo Voice Provider Extension for AgentOS.
+ *
+ * Provides an IVoiceCallProvider implementation backed by the Plivo Voice API,
+ * plus an ITool descriptor for programmatic voice call management.
+ *
+ * @module @framers/agentos-ext-voice-plivo
+ */
+import type { ExtensionContext, ExtensionPack, CallManager } from '@framers/agentos';
+export interface PlivoVoiceOptions {
+    /** Plivo Auth ID (overrides secrets/env). */
+    authId?: string;
+    /** Plivo Auth Token (overrides secrets/env). */
+    authToken?: string;
+    /** E.164 outbound caller ID (overrides secrets/env). */
+    fromNumber?: string;
+    /** Environment variable name for Auth ID (default: PLIVO_AUTH_ID). */
+    authIdEnv?: string;
+    /** Environment variable name for Auth Token (default: PLIVO_AUTH_TOKEN). */
+    authTokenEnv?: string;
+    /** Environment variable name for From Number (default: PLIVO_FROM_NUMBER). */
+    fromNumberEnv?: string;
+    /** Optional CallManager instance for the tool handler. */
+    callManager?: CallManager;
+    /** Extension priority (default: 50). */
+    priority?: number;
+}
+/**
+ * Create the Plivo Voice Provider extension pack.
+ *
+ * Resolves credentials from options, secrets map, or environment variables,
+ * then creates the PlivoVoiceService, PlivoVoiceProvider, and PlivoVoiceCallTool.
+ *
+ * @param context - Extension context with options, logger, and secrets.
+ * @returns An ExtensionPack with tool and voice-provider descriptors.
+ *
+ * @example
+ * ```typescript
+ * import { createExtensionPack } from '@framers/agentos-ext-voice-plivo';
+ *
+ * const pack = createExtensionPack({
+ *   options: {
+ *     authId: 'MAXXXXXXXXXX',
+ *     authToken: 'your-auth-token',
+ *     fromNumber: '+15551234567',
+ *     callManager: myCallManager,
+ *   },
+ * });
+ * ```
+ */
+export declare function createExtensionPack(context: ExtensionContext): ExtensionPack;
+export { PlivoVoiceService, type PlivoServiceConfig } from './PlivoVoiceService';
+export { PlivoVoiceProvider, createPlivoVoiceProvider } from './PlivoVoiceProvider';
+export { PlivoVoiceCallTool, 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;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AASrF,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAoFD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,aAAa,CAqE5E;AAGD,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAClF,eAAe,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,151 @@
+"use strict";
+// @ts-nocheck
+/**
+ * @fileoverview Plivo Voice Provider Extension for AgentOS.
+ *
+ * Provides an IVoiceCallProvider implementation backed by the Plivo Voice API,
+ * plus an ITool descriptor for programmatic voice call management.
+ *
+ * @module @framers/agentos-ext-voice-plivo
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlivoVoiceCallTool = exports.createPlivoVoiceProvider = exports.PlivoVoiceProvider = exports.PlivoVoiceService = void 0;
+exports.createExtensionPack = createExtensionPack;
+const PlivoVoiceService_1 = require("./PlivoVoiceService");
+const PlivoVoiceProvider_1 = require("./PlivoVoiceProvider");
+const voiceCall_1 = require("./tools/voiceCall");
+// ============================================================================
+// Secret/Env Resolution
+// ============================================================================
+function resolveSecret(key, optionsValue, secrets, secretKey, envName, ...envFallbacks) {
+    // 1. Direct option
+    if (optionsValue)
+        return optionsValue;
+    // 2. Secrets map
+    if (secrets?.[secretKey])
+        return secrets[secretKey];
+    // 3. Primary environment variable
+    if (process.env[envName])
+        return process.env[envName];
+    // 4. Fallback env vars
+    for (const fallback of envFallbacks) {
+        if (process.env[fallback])
+            return process.env[fallback];
+    }
+    throw new Error(`Plivo ${key} not found. Provide via options.${key}, secrets["${secretKey}"], or ${envName} env var.`);
+}
+// ============================================================================
+// CallManager Tool Handler Adapter
+// ============================================================================
+/**
+ * Adapts a CallManager instance into the VoiceCallToolHandler interface
+ * expected by the PlivoVoiceCallTool.
+ */
+function createCallManagerHandler(callManager) {
+    return {
+        async initiateCall(toNumber, message, mode) {
+            return callManager.initiateCall({ toNumber, message, mode });
+        },
+        speakText(callId, text) {
+            callManager.speakText(callId, text);
+        },
+        async hangupCall(callId) {
+            await callManager.hangupCall(callId);
+        },
+        getCallStatus(callId) {
+            return callManager.getCall(callId);
+        },
+        getActiveCalls() {
+            return callManager.getActiveCalls();
+        },
+    };
+}
+/**
+ * Stub handler used when no CallManager is provided.
+ * The tool will return errors explaining that a CallManager is required.
+ */
+function createStubHandler() {
+    const err = () => {
+        throw new Error('No CallManager configured. Provide options.callManager to enable voice call operations.');
+    };
+    return {
+        initiateCall: err,
+        speakText: err,
+        hangupCall: err,
+        getCallStatus: () => undefined,
+        getActiveCalls: () => [],
+    };
+}
+// ============================================================================
+// Extension Pack Factory
+// ============================================================================
+/**
+ * Create the Plivo Voice Provider extension pack.
+ *
+ * Resolves credentials from options, secrets map, or environment variables,
+ * then creates the PlivoVoiceService, PlivoVoiceProvider, and PlivoVoiceCallTool.
+ *
+ * @param context - Extension context with options, logger, and secrets.
+ * @returns An ExtensionPack with tool and voice-provider descriptors.
+ *
+ * @example
+ * ```typescript
+ * import { createExtensionPack } from '@framers/agentos-ext-voice-plivo';
+ *
+ * const pack = createExtensionPack({
+ *   options: {
+ *     authId: 'MAXXXXXXXXXX',
+ *     authToken: 'your-auth-token',
+ *     fromNumber: '+15551234567',
+ *     callManager: myCallManager,
+ *   },
+ * });
+ * ```
+ */
+function createExtensionPack(context) {
+    const options = (context.options ?? {});
+    // Resolve credentials
+    const authId = resolveSecret('authId', options.authId, options.secrets, 'plivo.authId', options.authIdEnv ?? 'PLIVO_AUTH_ID', 'PLIVO_AUTH_ID');
+    const authToken = resolveSecret('authToken', options.authToken, options.secrets, 'plivo.authToken', options.authTokenEnv ?? 'PLIVO_AUTH_TOKEN', 'PLIVO_AUTH_TOKEN');
+    const fromNumber = resolveSecret('fromNumber', options.fromNumber, options.secrets, 'plivo.fromNumber', options.fromNumberEnv ?? 'PLIVO_FROM_NUMBER', 'PLIVO_FROM_NUMBER', 'PLIVO_PHONE_NUMBER');
+    // Create service and provider
+    const serviceConfig = { authId, authToken, fromNumber };
+    const service = new PlivoVoiceService_1.PlivoVoiceService(serviceConfig);
+    const provider = (0, PlivoVoiceProvider_1.createPlivoVoiceProvider)(service, authToken);
+    // Create tool with CallManager handler or stub
+    const handler = options.callManager
+        ? createCallManagerHandler(options.callManager)
+        : createStubHandler();
+    const voiceCallTool = new voiceCall_1.PlivoVoiceCallTool(handler);
+    const priority = options.priority ?? 50;
+    return {
+        name: '@framers/agentos-ext-voice-plivo',
+        version: '0.1.0',
+        descriptors: [
+            { id: 'plivoVoiceCall', kind: 'tool', priority, payload: voiceCallTool },
+            { id: 'plivoVoiceProvider', kind: 'voice-provider', priority, payload: provider },
+        ],
+        onActivate: async () => {
+            await service.initialize();
+            // If a CallManager was provided, register the provider
+            if (options.callManager) {
+                options.callManager.registerProvider(provider);
+            }
+            context.logger?.info('[PlivoVoice] Extension activated');
+        },
+        onDeactivate: async () => {
+            await service.shutdown();
+            context.logger?.info('[PlivoVoice] Extension deactivated');
+        },
+    };
+}
+// Re-export public API
+var PlivoVoiceService_2 = require("./PlivoVoiceService");
+Object.defineProperty(exports, "PlivoVoiceService", { enumerable: true, get: function () { return PlivoVoiceService_2.PlivoVoiceService; } });
+var PlivoVoiceProvider_2 = require("./PlivoVoiceProvider");
+Object.defineProperty(exports, "PlivoVoiceProvider", { enumerable: true, get: function () { return PlivoVoiceProvider_2.PlivoVoiceProvider; } });
+Object.defineProperty(exports, "createPlivoVoiceProvider", { enumerable: true, get: function () { return PlivoVoiceProvider_2.createPlivoVoiceProvider; } });
+var voiceCall_2 = require("./tools/voiceCall");
+Object.defineProperty(exports, "PlivoVoiceCallTool", { enumerable: true, get: function () { return voiceCall_2.PlivoVoiceCallTool; } });
+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":";AAAA,cAAc;AACd;;;;;;;GAOG;;;AAuIH,kDAqEC;AAzMD,2DAAiF;AACjF,6DAAoF;AACpF,iDAAkF;AAyBlF,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E,SAAS,aAAa,CACpB,GAAW,EACX,YAAgC,EAChC,OAA2C,EAC3C,SAAiB,EACjB,OAAe,EACf,GAAG,YAAsB;IAEzB,mBAAmB;IACnB,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,iBAAiB;IACjB,IAAI,OAAO,EAAE,CAAC,SAAS,CAAC;QAAE,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpD,kCAAkC;IAClC,IAAI,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;IAEvD,uBAAuB;IACvB,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;QACpC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;IAC3D,CAAC;IAED,MAAM,IAAI,KAAK,CACb,SAAS,GAAG,mCAAmC,GAAG,cAAc,SAAS,UAAU,OAAO,WAAW,CACtG,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,mCAAmC;AACnC,+EAA+E;AAE/E;;;GAGG;AACH,SAAS,wBAAwB,CAAC,WAAwB;IACxD,OAAO;QACL,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI;YACxC,OAAO,WAAW,CAAC,YAAY,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/D,CAAC;QACD,SAAS,CAAC,MAAM,EAAE,IAAI;YACpB,WAAW,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,MAAM;YACrB,MAAM,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC;QACD,aAAa,CAAC,MAAM;YAClB,OAAO,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;QACD,cAAc;YACZ,OAAO,WAAW,CAAC,cAAc,EAAE,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB;IACxB,MAAM,GAAG,GAAG,GAAG,EAAE;QACf,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;IACJ,CAAC,CAAC;IACF,OAAO;QACL,YAAY,EAAE,GAAG;QACjB,SAAS,EAAE,GAAG;QACd,UAAU,EAAE,GAAG;QACf,aAAa,EAAE,GAAG,EAAE,CAAC,SAAS;QAC9B,cAAc,EAAE,GAAG,EAAE,CAAC,EAAE;KACzB,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,mBAAmB,CAAC,OAAyB;IAC3D,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAErC,CAAC;IAEF,sBAAsB;IACtB,MAAM,MAAM,GAAG,aAAa,CAC1B,QAAQ,EACR,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,OAAO,EACf,cAAc,EACd,OAAO,CAAC,SAAS,IAAI,eAAe,EACpC,eAAe,CAChB,CAAC;IAEF,MAAM,SAAS,GAAG,aAAa,CAC7B,WAAW,EACX,OAAO,CAAC,SAAS,EACjB,OAAO,CAAC,OAAO,EACf,iBAAiB,EACjB,OAAO,CAAC,YAAY,IAAI,kBAAkB,EAC1C,kBAAkB,CACnB,CAAC;IAEF,MAAM,UAAU,GAAG,aAAa,CAC9B,YAAY,EACZ,OAAO,CAAC,UAAU,EAClB,OAAO,CAAC,OAAO,EACf,kBAAkB,EAClB,OAAO,CAAC,aAAa,IAAI,mBAAmB,EAC5C,mBAAmB,EACnB,oBAAoB,CACrB,CAAC;IAEF,8BAA8B;IAC9B,MAAM,aAAa,GAAuB,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;IAC5E,MAAM,OAAO,GAAG,IAAI,qCAAiB,CAAC,aAAa,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,IAAA,6CAAwB,EAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAE9D,+CAA+C;IAC/C,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW;QACjC,CAAC,CAAC,wBAAwB,CAAC,OAAO,CAAC,WAAW,CAAC;QAC/C,CAAC,CAAC,iBAAiB,EAAE,CAAC;IACxB,MAAM,aAAa,GAAG,IAAI,8BAAkB,CAAC,OAAO,CAAC,CAAC;IAEtD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IAExC,OAAO;QACL,IAAI,EAAE,kCAAkC;QACxC,OAAO,EAAE,OAAO;QAChB,WAAW,EAAE;YACX,EAAE,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,EAAE;YACxE,EAAE,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE;SAClF;QACD,UAAU,EAAE,KAAK,IAAI,EAAE;YACrB,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;YAE3B,uDAAuD;YACvD,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;gBACxB,OAAO,CAAC,WAAW,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;YACjD,CAAC;YAED,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,kCAAkC,CAAC,CAAC;QAC3D,CAAC;QACD,YAAY,EAAE,KAAK,IAAI,EAAE;YACvB,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzB,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,oCAAoC,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,uBAAuB;AACvB,yDAAiF;AAAxE,sHAAA,iBAAiB,OAAA;AAC1B,2DAAoF;AAA3E,wHAAA,kBAAkB,OAAA;AAAE,8HAAA,wBAAwB,OAAA;AACrD,+CAAkF;AAAzE,+GAAA,kBAAkB,OAAA;AAC3B,kBAAe,mBAAmB,CAAC"}

package/dist/tools/voiceCall.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview ITool implementation for Plivo voice calls.
+ *
+ * Provides the `plivoVoiceCall` tool that agents can invoke to make
+ * outbound phone calls, speak text into active calls, hang up calls,
+ * and query call status.
+ *
+ * Follows the same VoiceCallTool pattern used by Twilio/Telnyx extensions.
+ *
+ * @module @framers/agentos-ext-voice-plivo/tools/voiceCall
+ */
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos';
+import type { CallMode, CallRecord } from '@framers/agentos';
+/**
+ * Abstraction over the CallManager's operations so the tool
+ * does not depend directly on CallManager internals.
+ */
+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 status of a call by ID. */
+    getCallStatus(callId: string): CallRecord | undefined;
+    /** Get all active (non-terminal) calls. */
+    getActiveCalls(): CallRecord[];
+}
+type VoiceCallAction = 'call' | 'speak' | 'hangup' | 'status' | 'list';
+interface VoiceCallArgs {
+    /** Action to perform. */
+    action: VoiceCallAction;
+    /** E.164 phone number to call (for 'call' action). */
+    toNumber?: string;
+    /** Call ID (for 'speak', 'hangup', 'status' actions). */
+    callId?: string;
+    /** Text message to speak (for 'call' in notify mode, or 'speak' action). */
+    message?: string;
+    /** Call mode: 'notify' or 'conversation' (for 'call' action). */
+    mode?: CallMode;
+}
+export declare class PlivoVoiceCallTool implements ITool<VoiceCallArgs> {
+    private readonly handler;
+    readonly id = "plivoVoiceCall";
+    readonly name = "plivoVoiceCall";
+    readonly displayName = "Plivo Voice Call";
+    readonly description: string;
+    readonly category = "telephony";
+    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;
+            };
+            callId: {
+                type: string;
+                description: string;
+            };
+            message: {
+                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;
+            };
+            calls: {
+                type: string;
+                description: string;
+                items: {
+                    type: string;
+                };
+            };
+        };
+    };
+    constructor(handler: VoiceCallToolHandler);
+    execute(args: VoiceCallArgs, _context: ToolExecutionContext): Promise<ToolExecutionResult>;
+    validateArgs(args: Record<string, any>): {
+        isValid: boolean;
+        errors?: string[];
+    };
+    private handleCall;
+    private handleSpeak;
+    private handleHangup;
+    private handleStatus;
+    private handleList;
+}
+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;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACX,MAAM,kBAAkB,CAAC;AAM1B;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,iCAAiC;IACjC,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,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,sCAAsC;IACtC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IACtD,2CAA2C;IAC3C,cAAc,IAAI,UAAU,EAAE,CAAC;CAChC;AAMD,KAAK,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvE,UAAU,aAAa;IACrB,yBAAyB;IACzB,MAAM,EAAE,eAAe,CAAC;IACxB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAMD,qBAAa,kBAAmB,YAAW,KAAK,CAAC,aAAa,CAAC;IAuDjD,OAAO,CAAC,QAAQ,CAAC,OAAO;IAtDpC,SAAgB,EAAE,oBAAoB;IACtC,SAAgB,IAAI,oBAAoB;IACxC,SAAgB,WAAW,sBAAsB;IACjD,SAAgB,WAAW,SAG6D;IACxF,SAAgB,QAAQ,eAAe;IACvC,SAAgB,OAAO,WAAW;IAClC,SAAgB,cAAc,QAAQ;IAEtC,SAAgB,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;MA4BzB;IAEF,SAAgB,YAAY;;;;;;;;;;;;;;;;;;;MAW1B;gBAE2B,OAAO,EAAE,oBAAoB;IAEpD,OAAO,CACX,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAwB/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;YA2BlE,UAAU;IAyBxB,OAAO,CAAC,WAAW;YAgBL,YAAY;IAa1B,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,UAAU;CAmBnB"}