@framers/agentos-ext-amazon-polly 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: amazon-polly
+description: Neural text-to-speech via Amazon Polly
+category: voice
+---
+
+# Amazon Polly TTS
+
+Text-to-speech synthesis using Amazon Polly's Neural engine with MP3 output.
+
+## Setup
+
+Set the following secrets in your environment or agent secrets store:
+
+| Secret              | Description              |
+|---------------------|--------------------------|
+| `AWS_ACCESS_KEY_ID` | IAM access key ID        |
+| `AWS_SECRET_ACCESS_KEY` | IAM secret access key |
+| `AWS_REGION`        | AWS region (default `us-east-1`) |
+
+## Features
+
+- Neural engine (high-quality, natural-sounding voices)
+- MP3 audio output
+- `listAvailableVoices()` to enumerate all Polly voices
+- Default voice: `Joanna` (en-US, Neural)
+
+## Configuration
+
+In `agent.config.json`:
+
+```json
+{
+  "voice": {
+    "tts": "amazon-polly"
+  }
+}
+```
+
+Provider-specific options:
+
+```json
+{
+  "voice": {
+    "tts": "amazon-polly",
+    "providerOptions": {
+      "voice": "Matthew"
+    }
+  }
+}
+```

package/dist/AmazonPollyTTSProvider.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @file AmazonPollyTTSProvider.ts
+ * @description Text-to-speech provider backed by Amazon Polly Neural engine.
+ *
+ * The provider uses the AWS SDK v3 `@aws-sdk/client-polly` package, which is
+ * declared as a peer dependency so it is only loaded at runtime.
+ *
+ * Audio is synthesised in MP3 format using the Neural engine.  The response
+ * `AudioStream` (a `ReadableStream` in Node 18+) is fully collected into a
+ * `Buffer` before being returned to the caller.
+ *
+ * @module amazon-polly
+ */
+/**
+ * Constructor options for {@link AmazonPollyTTSProvider}.
+ */
+export interface AmazonPollyCredentials {
+    /** AWS IAM access key ID. */
+    accessKeyId: string;
+    /** AWS IAM secret access key. */
+    secretAccessKey: string;
+    /**
+     * AWS region where the Polly endpoint lives.
+     * @defaultValue `'us-east-1'`
+     */
+    region?: string;
+}
+/**
+ * A voice available on Amazon Polly.
+ *
+ * Mirrors the generic `SpeechVoice` shape used across the AgentOS voice pipeline.
+ */
+export interface SpeechVoice {
+    /** Provider-specific voice identifier (e.g. `'Joanna'`). */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Primary BCP-47 language code supported by this voice. */
+    languageCode: string;
+    /** Biological gender label from the API (`'Male'`, `'Female'`). */
+    gender?: string;
+}
+/**
+ * Synthesised audio returned by {@link AmazonPollyTTSProvider.synthesize}.
+ */
+export interface SynthesisResult {
+    /** Raw MP3 audio bytes. */
+    audioBuffer: Buffer;
+    /** MIME type of the audio data. Always `'audio/mpeg'` for this provider. */
+    mimeType: 'audio/mpeg';
+    /** Billable cost of the request (placeholder — always 0). */
+    cost: number;
+}
+/**
+ * Per-call synthesis options forwarded to the Amazon Polly API.
+ */
+export interface AmazonPollyTTSOptions {
+    /**
+     * Polly VoiceId (e.g. `'Joanna'`, `'Matthew'`).
+     * @defaultValue `'Joanna'`
+     * @see {@link https://docs.aws.amazon.com/polly/latest/dg/voicelist.html}
+     */
+    voice?: string;
+}
+/**
+ * Amazon Polly text-to-speech provider.
+ *
+ * Implements the `TextToSpeechProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export declare class AmazonPollyTTSProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    readonly id = "amazon-polly";
+    /** Lazily initialised Polly client. */
+    private _client;
+    /** Client configuration stored for lazy initialisation. */
+    private readonly _config;
+    /**
+     * Create a new {@link AmazonPollyTTSProvider}.
+     *
+     * @param credentials - AWS credentials and optional region.
+     */
+    constructor(credentials: AmazonPollyCredentials);
+    /**
+     * Lazily create and return the `PollyClient` instance.
+     */
+    private _getClient;
+    /**
+     * Drain a Node.js `Readable` or a WHATWG `ReadableStream` into a `Buffer`.
+     *
+     * Amazon Polly v3 returns the audio stream as a `Readable` in Node
+     * environments.  This helper handles both the Node stream API and the
+     * WHATWG `ReadableStream` API (for edge runtimes).
+     *
+     * @param stream - The audio stream from the Polly response.
+     * @returns A `Buffer` containing the full audio payload.
+     */
+    private _collectStream;
+    /**
+     * Synthesise text to MP3 audio using Amazon Polly Neural engine.
+     *
+     * @param text    - Plain text to synthesise.
+     * @param options - Optional per-call parameters (voice ID).
+     * @returns {@link SynthesisResult} containing the raw MP3 buffer.
+     */
+    synthesize(text: string, options?: AmazonPollyTTSOptions): Promise<SynthesisResult>;
+    /**
+     * List all voices available on Amazon Polly.
+     *
+     * @returns Array of {@link SpeechVoice} objects.
+     */
+    listAvailableVoices(): Promise<SpeechVoice[]>;
+}
+//# sourceMappingURL=AmazonPollyTTSProvider.d.ts.map

package/dist/AmazonPollyTTSProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AmazonPollyTTSProvider.d.ts","sourceRoot":"","sources":["../src/AmazonPollyTTSProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IACX,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,QAAQ,EAAE,YAAY,CAAC;IACvB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,sBAAsB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,kBAAkB;IAE7B,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAA4B;IAE3C,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAE3D;;;;OAIG;gBACS,WAAW,EAAE,sBAAsB;IAY/C;;OAEG;YACW,UAAU;IAcxB;;;;;;;;;OASG;YACW,cAAc;IAuC5B;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAsBzF;;;;OAIG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAcpD"}

package/dist/AmazonPollyTTSProvider.js

@@ -0,0 +1,142 @@
+/**
+ * @file AmazonPollyTTSProvider.ts
+ * @description Text-to-speech provider backed by Amazon Polly Neural engine.
+ *
+ * The provider uses the AWS SDK v3 `@aws-sdk/client-polly` package, which is
+ * declared as a peer dependency so it is only loaded at runtime.
+ *
+ * Audio is synthesised in MP3 format using the Neural engine.  The response
+ * `AudioStream` (a `ReadableStream` in Node 18+) is fully collected into a
+ * `Buffer` before being returned to the caller.
+ *
+ * @module amazon-polly
+ */
+/**
+ * Amazon Polly text-to-speech provider.
+ *
+ * Implements the `TextToSpeechProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class AmazonPollyTTSProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    id = 'amazon-polly';
+    /** Lazily initialised Polly client. */
+    _client = null;
+    /** Client configuration stored for lazy initialisation. */
+    _config;
+    /**
+     * Create a new {@link AmazonPollyTTSProvider}.
+     *
+     * @param credentials - AWS credentials and optional region.
+     */
+    constructor(credentials) {
+        this._config = {
+            accessKeyId: credentials.accessKeyId,
+            secretAccessKey: credentials.secretAccessKey,
+            region: credentials.region ?? 'us-east-1',
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Lazily create and return the `PollyClient` instance.
+     */
+    async _getClient() {
+        if (!this._client) {
+            const { PollyClient } = await import('@aws-sdk/client-polly');
+            this._client = new PollyClient({
+                region: this._config.region,
+                credentials: {
+                    accessKeyId: this._config.accessKeyId,
+                    secretAccessKey: this._config.secretAccessKey,
+                },
+            });
+        }
+        return this._client;
+    }
+    /**
+     * Drain a Node.js `Readable` or a WHATWG `ReadableStream` into a `Buffer`.
+     *
+     * Amazon Polly v3 returns the audio stream as a `Readable` in Node
+     * environments.  This helper handles both the Node stream API and the
+     * WHATWG `ReadableStream` API (for edge runtimes).
+     *
+     * @param stream - The audio stream from the Polly response.
+     * @returns A `Buffer` containing the full audio payload.
+     */
+    async _collectStream(stream) {
+        // Node.js Readable (most common in server environments)
+        if (stream !== null &&
+            typeof stream === 'object' &&
+            typeof stream.on === 'function') {
+            return new Promise((resolve, reject) => {
+                const chunks = [];
+                const readable = stream;
+                readable.on('data', (chunk) => chunks.push(chunk));
+                readable.on('end', () => resolve(Buffer.concat(chunks)));
+                readable.on('error', reject);
+            });
+        }
+        // WHATWG ReadableStream (edge runtimes)
+        if (stream !== null &&
+            typeof stream === 'object' &&
+            typeof stream.getReader === 'function') {
+            const reader = stream.getReader();
+            const chunks = [];
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    chunks.push(value);
+            }
+            return Buffer.concat(chunks);
+        }
+        throw new TypeError('Unsupported AudioStream type returned by Polly');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Synthesise text to MP3 audio using Amazon Polly Neural engine.
+     *
+     * @param text    - Plain text to synthesise.
+     * @param options - Optional per-call parameters (voice ID).
+     * @returns {@link SynthesisResult} containing the raw MP3 buffer.
+     */
+    async synthesize(text, options) {
+        const client = await this._getClient();
+        const { SynthesizeSpeechCommand } = await import('@aws-sdk/client-polly');
+        const response = await client.send(new SynthesizeSpeechCommand({
+            Engine: 'neural',
+            OutputFormat: 'mp3',
+            Text: text,
+            VoiceId: options?.voice ?? 'Joanna',
+        }));
+        const audioBuffer = await this._collectStream(response.AudioStream);
+        return {
+            audioBuffer,
+            mimeType: 'audio/mpeg',
+            cost: 0,
+        };
+    }
+    /**
+     * List all voices available on Amazon Polly.
+     *
+     * @returns Array of {@link SpeechVoice} objects.
+     */
+    async listAvailableVoices() {
+        const client = await this._getClient();
+        const { DescribeVoicesCommand } = await import('@aws-sdk/client-polly');
+        const response = await client.send(new DescribeVoicesCommand({}));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (response.Voices ?? []).map((v) => ({
+            id: v.Id ?? '',
+            name: v.Name ?? '',
+            languageCode: v.LanguageCode ?? '',
+            gender: v.Gender ?? undefined,
+        }));
+    }
+}
+//# sourceMappingURL=AmazonPollyTTSProvider.js.map

package/dist/AmazonPollyTTSProvider.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Amazon Polly TTS extension pack.
+ *
+ * Exports the main {@link createAmazonPollyTTS} factory function and the
+ * {@link createExtensionPack} bridge function conforming to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createAmazonPollyTTS } from '@framers/agentos-ext-amazon-polly';
+ *
+ * const tts = createAmazonPollyTTS({
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   region: 'us-east-1',
+ * });
+ * const result = await tts.synthesize('Hello, world!');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-amazon-polly" }] }
+ * ```
+ *
+ * @module amazon-polly
+ */
+import { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+import type { AmazonPollyCredentials } from './AmazonPollyTTSProvider.js';
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+    id: string;
+    kind: string;
+    payload: unknown;
+    enableByDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+    id: string;
+    descriptors: ExtensionDescriptor[];
+}
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+    getSecret?: (id: string) => string | undefined;
+    options?: Record<string, unknown>;
+}
+/**
+ * Create a standalone {@link AmazonPollyTTSProvider} instance.
+ *
+ * @param credentials - AWS credentials and optional region.
+ * @returns Configured {@link AmazonPollyTTSProvider}.
+ */
+export declare function createAmazonPollyTTS(credentials: AmazonPollyCredentials): AmazonPollyTTSProvider;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally
+ * `AWS_REGION` from the pack context secrets, then returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link AmazonPollyTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+export type { AmazonPollyCredentials, AmazonPollyTTSOptions, SpeechVoice, SynthesisResult, } from './AmazonPollyTTSProvider.js';
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAM1E,2DAA2D;AAC3D,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,4DAA4D;AAC5D,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AASD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,sBAAsB,GAAG,sBAAsB,CAEhG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAmBhF;AAMD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,eAAe,GAChB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,77 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Amazon Polly TTS extension pack.
+ *
+ * Exports the main {@link createAmazonPollyTTS} factory function and the
+ * {@link createExtensionPack} bridge function conforming to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createAmazonPollyTTS } from '@framers/agentos-ext-amazon-polly';
+ *
+ * const tts = createAmazonPollyTTS({
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   region: 'us-east-1',
+ * });
+ * const result = await tts.synthesize('Hello, world!');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-amazon-polly" }] }
+ * ```
+ *
+ * @module amazon-polly
+ */
+import { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_TTS = 'tts-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link AmazonPollyTTSProvider} instance.
+ *
+ * @param credentials - AWS credentials and optional region.
+ * @returns Configured {@link AmazonPollyTTSProvider}.
+ */
+export function createAmazonPollyTTS(credentials) {
+    return new AmazonPollyTTSProvider(credentials);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally
+ * `AWS_REGION` from the pack context secrets, then returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link AmazonPollyTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const provider = new AmazonPollyTTSProvider({
+        accessKeyId: context.getSecret?.('AWS_ACCESS_KEY_ID') ?? '',
+        secretAccessKey: context.getSecret?.('AWS_SECRET_ACCESS_KEY') ?? '',
+        region: context.getSecret?.('AWS_REGION'),
+    });
+    return {
+        id: 'amazon-polly',
+        descriptors: [
+            {
+                id: 'amazon-polly',
+                kind: EXTENSION_KIND_TTS,
+                payload: provider,
+                enableByDefault: true,
+                metadata: { providerId: 'amazon-polly' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AA4BrE,uEAAuE;AACvE,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmC;IACtE,OAAO,IAAI,sBAAsB,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,QAAQ,GAAG,IAAI,sBAAsB,CAAC;QAC1C,WAAW,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,mBAAmB,CAAC,IAAI,EAAE;QAC3D,eAAe,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,uBAAuB,CAAC,IAAI,EAAE;QACnE,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,YAAY,CAAC;KAC1C,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,cAAc;gBAClB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,QAAQ;gBACjB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE;aACzC;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-amazon-polly",
+  "version": "0.1.0",
+  "description": "Text-to-speech via Amazon Polly",
+  "kind": "tts-provider",
+  "extensionId": "amazon-polly",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@framers/agentos-ext-amazon-polly",
+  "version": "0.2.0",
+  "description": "Text-to-speech via Amazon Polly for AgentOS voice pipeline",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "SKILL.md",
+    "manifest.json"
+  ],
+  "peerDependencies": {
+    "@framers/agentos": "^0.1.0",
+    "@aws-sdk/client-polly": "^3.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-polly": "^3.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "@framers/agentos": "0.1.94"
+  },
+  "license": "MIT",
+  "author": "Frame.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/voice/amazon-polly"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/AmazonPollyTTSProvider.ts

@@ -0,0 +1,220 @@
+/**
+ * @file AmazonPollyTTSProvider.ts
+ * @description Text-to-speech provider backed by Amazon Polly Neural engine.
+ *
+ * The provider uses the AWS SDK v3 `@aws-sdk/client-polly` package, which is
+ * declared as a peer dependency so it is only loaded at runtime.
+ *
+ * Audio is synthesised in MP3 format using the Neural engine.  The response
+ * `AudioStream` (a `ReadableStream` in Node 18+) is fully collected into a
+ * `Buffer` before being returned to the caller.
+ *
+ * @module amazon-polly
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type PollyClient = any;
+
+/**
+ * Constructor options for {@link AmazonPollyTTSProvider}.
+ */
+export interface AmazonPollyCredentials {
+  /** AWS IAM access key ID. */
+  accessKeyId: string;
+  /** AWS IAM secret access key. */
+  secretAccessKey: string;
+  /**
+   * AWS region where the Polly endpoint lives.
+   * @defaultValue `'us-east-1'`
+   */
+  region?: string;
+}
+
+/**
+ * A voice available on Amazon Polly.
+ *
+ * Mirrors the generic `SpeechVoice` shape used across the AgentOS voice pipeline.
+ */
+export interface SpeechVoice {
+  /** Provider-specific voice identifier (e.g. `'Joanna'`). */
+  id: string;
+  /** Human-readable display name. */
+  name: string;
+  /** Primary BCP-47 language code supported by this voice. */
+  languageCode: string;
+  /** Biological gender label from the API (`'Male'`, `'Female'`). */
+  gender?: string;
+}
+
+/**
+ * Synthesised audio returned by {@link AmazonPollyTTSProvider.synthesize}.
+ */
+export interface SynthesisResult {
+  /** Raw MP3 audio bytes. */
+  audioBuffer: Buffer;
+  /** MIME type of the audio data. Always `'audio/mpeg'` for this provider. */
+  mimeType: 'audio/mpeg';
+  /** Billable cost of the request (placeholder — always 0). */
+  cost: number;
+}
+
+/**
+ * Per-call synthesis options forwarded to the Amazon Polly API.
+ */
+export interface AmazonPollyTTSOptions {
+  /**
+   * Polly VoiceId (e.g. `'Joanna'`, `'Matthew'`).
+   * @defaultValue `'Joanna'`
+   * @see {@link https://docs.aws.amazon.com/polly/latest/dg/voicelist.html}
+   */
+  voice?: string;
+}
+
+/**
+ * Amazon Polly text-to-speech provider.
+ *
+ * Implements the `TextToSpeechProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class AmazonPollyTTSProvider {
+  /** Stable provider identifier used by the AgentOS extension registry. */
+  readonly id = 'amazon-polly';
+
+  /** Lazily initialised Polly client. */
+  private _client: PollyClient | null = null;
+
+  /** Client configuration stored for lazy initialisation. */
+  private readonly _config: Required<AmazonPollyCredentials>;
+
+  /**
+   * Create a new {@link AmazonPollyTTSProvider}.
+   *
+   * @param credentials - AWS credentials and optional region.
+   */
+  constructor(credentials: AmazonPollyCredentials) {
+    this._config = {
+      accessKeyId: credentials.accessKeyId,
+      secretAccessKey: credentials.secretAccessKey,
+      region: credentials.region ?? 'us-east-1',
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Lazily create and return the `PollyClient` instance.
+   */
+  private async _getClient(): Promise<PollyClient> {
+    if (!this._client) {
+      const { PollyClient } = await import('@aws-sdk/client-polly');
+      this._client = new PollyClient({
+        region: this._config.region,
+        credentials: {
+          accessKeyId: this._config.accessKeyId,
+          secretAccessKey: this._config.secretAccessKey,
+        },
+      });
+    }
+    return this._client;
+  }
+
+  /**
+   * Drain a Node.js `Readable` or a WHATWG `ReadableStream` into a `Buffer`.
+   *
+   * Amazon Polly v3 returns the audio stream as a `Readable` in Node
+   * environments.  This helper handles both the Node stream API and the
+   * WHATWG `ReadableStream` API (for edge runtimes).
+   *
+   * @param stream - The audio stream from the Polly response.
+   * @returns A `Buffer` containing the full audio payload.
+   */
+  private async _collectStream(stream: unknown): Promise<Buffer> {
+    // Node.js Readable (most common in server environments)
+    if (
+      stream !== null &&
+      typeof stream === 'object' &&
+      typeof (stream as { on?: unknown }).on === 'function'
+    ) {
+      return new Promise<Buffer>((resolve, reject) => {
+        const chunks: Buffer[] = [];
+        const readable = stream as NodeJS.ReadableStream;
+        readable.on('data', (chunk: Buffer) => chunks.push(chunk));
+        readable.on('end', () => resolve(Buffer.concat(chunks)));
+        readable.on('error', reject);
+      });
+    }
+
+    // WHATWG ReadableStream (edge runtimes)
+    if (
+      stream !== null &&
+      typeof stream === 'object' &&
+      typeof (stream as { getReader?: unknown }).getReader === 'function'
+    ) {
+      const reader = (stream as ReadableStream<Uint8Array>).getReader();
+      const chunks: Uint8Array[] = [];
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) chunks.push(value);
+      }
+      return Buffer.concat(chunks);
+    }
+
+    throw new TypeError('Unsupported AudioStream type returned by Polly');
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Synthesise text to MP3 audio using Amazon Polly Neural engine.
+   *
+   * @param text    - Plain text to synthesise.
+   * @param options - Optional per-call parameters (voice ID).
+   * @returns {@link SynthesisResult} containing the raw MP3 buffer.
+   */
+  async synthesize(text: string, options?: AmazonPollyTTSOptions): Promise<SynthesisResult> {
+    const client = await this._getClient();
+
+    const { SynthesizeSpeechCommand } = await import('@aws-sdk/client-polly');
+    const response = await client.send(
+      new SynthesizeSpeechCommand({
+        Engine: 'neural',
+        OutputFormat: 'mp3',
+        Text: text,
+        VoiceId: options?.voice ?? 'Joanna',
+      }),
+    );
+
+    const audioBuffer = await this._collectStream(response.AudioStream);
+
+    return {
+      audioBuffer,
+      mimeType: 'audio/mpeg',
+      cost: 0,
+    };
+  }
+
+  /**
+   * List all voices available on Amazon Polly.
+   *
+   * @returns Array of {@link SpeechVoice} objects.
+   */
+  async listAvailableVoices(): Promise<SpeechVoice[]> {
+    const client = await this._getClient();
+
+    const { DescribeVoicesCommand } = await import('@aws-sdk/client-polly');
+    const response = await client.send(new DescribeVoicesCommand({}));
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (response.Voices ?? []).map((v: any) => ({
+      id: v.Id ?? '',
+      name: v.Name ?? '',
+      languageCode: v.LanguageCode ?? '',
+      gender: v.Gender ?? undefined,
+    }));
+  }
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Amazon Polly TTS extension pack.
+ *
+ * Exports the main {@link createAmazonPollyTTS} factory function and the
+ * {@link createExtensionPack} bridge function conforming to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createAmazonPollyTTS } from '@framers/agentos-ext-amazon-polly';
+ *
+ * const tts = createAmazonPollyTTS({
+ *   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *   region: 'us-east-1',
+ * });
+ * const result = await tts.synthesize('Hello, world!');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-amazon-polly" }] }
+ * ```
+ *
+ * @module amazon-polly
+ */
+
+import { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+import type { AmazonPollyCredentials } from './AmazonPollyTTSProvider.js';
+
+// ---------------------------------------------------------------------------
+// Local interface mirrors — avoids a hard runtime dep on @framers/agentos
+// ---------------------------------------------------------------------------
+
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+  id: string;
+  kind: string;
+  payload: unknown;
+  enableByDefault?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+  id: string;
+  descriptors: ExtensionDescriptor[];
+}
+
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+  getSecret?: (id: string) => string | undefined;
+  options?: Record<string, unknown>;
+}
+
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_TTS = 'tts-provider';
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a standalone {@link AmazonPollyTTSProvider} instance.
+ *
+ * @param credentials - AWS credentials and optional region.
+ * @returns Configured {@link AmazonPollyTTSProvider}.
+ */
+export function createAmazonPollyTTS(credentials: AmazonPollyCredentials): AmazonPollyTTSProvider {
+  return new AmazonPollyTTSProvider(credentials);
+}
+
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally
+ * `AWS_REGION` from the pack context secrets, then returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link AmazonPollyTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  const provider = new AmazonPollyTTSProvider({
+    accessKeyId: context.getSecret?.('AWS_ACCESS_KEY_ID') ?? '',
+    secretAccessKey: context.getSecret?.('AWS_SECRET_ACCESS_KEY') ?? '',
+    region: context.getSecret?.('AWS_REGION'),
+  });
+
+  return {
+    id: 'amazon-polly',
+    descriptors: [
+      {
+        id: 'amazon-polly',
+        kind: EXTENSION_KIND_TTS,
+        payload: provider,
+        enableByDefault: true,
+        metadata: { providerId: 'amazon-polly' },
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { AmazonPollyTTSProvider } from './AmazonPollyTTSProvider.js';
+export type {
+  AmazonPollyCredentials,
+  AmazonPollyTTSOptions,
+  SpeechVoice,
+  SynthesisResult,
+} from './AmazonPollyTTSProvider.js';