@framers/agentos-ext-piper 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,18 @@
+# piper — Offline TTS Extension Pack
+
+Provides offline text-to-speech by spawning the [Piper](https://github.com/rhasspy/piper) binary.
+
+## Configuration
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `binaryPath` | `PIPER_BIN` env or `piper` | Path to the Piper executable |
+| `modelPath` | `PIPER_MODEL_PATH` env or `~/.agentos/models/piper/en_US-lessac-medium.onnx` | ONNX model file |
+| `maxBufferBytes` | `10485760` (10 MB) | Maximum WAV output size |
+| `timeoutMs` | `30000` | Process timeout in milliseconds |
+
+## Features
+- Fully offline — no network required after model download
+- Zero npm dependencies (uses `child_process.spawn`)
+- Returns WAV audio (`audio/wav`)
+- Cost always 0

package/dist/PiperTTSProvider.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file PiperTTSProvider.ts
+ * @description Offline text-to-speech provider that invokes the Piper binary.
+ *
+ * [Piper](https://github.com/rhasspy/piper) is a fast, local neural TTS
+ * system.  This provider spawns the binary via `child_process.spawn`, writes
+ * the input text to `stdin`, and collects the WAV audio written to `stdout`.
+ *
+ * No npm dependencies are required beyond Node's built-in `child_process`
+ * module.  The Piper binary must be installed separately and be accessible
+ * via the `binaryPath` option or the `PIPER_BIN` environment variable
+ * (defaults to `piper`, which expects the binary to be on `PATH`).
+ *
+ * @module piper
+ */
+/**
+ * Constructor options for {@link PiperTTSProvider}.
+ */
+export interface PiperTTSProviderOptions {
+    /**
+     * Absolute path to the Piper executable, or just `'piper'` if it is on
+     * `PATH`.  Resolved from `PIPER_BIN` env var when omitted.
+     * @defaultValue `process.env.PIPER_BIN ?? 'piper'`
+     */
+    binaryPath?: string;
+    /**
+     * Absolute path to the ONNX voice model file.
+     * Resolved from `PIPER_MODEL_PATH` env var when omitted.
+     * @defaultValue `~/.agentos/models/piper/en_US-lessac-medium.onnx`
+     */
+    modelPath?: string;
+    /**
+     * Maximum number of bytes accepted from Piper's stdout.
+     * Prevents runaway memory usage if the binary misbehaves.
+     * @defaultValue `10485760` (10 MB)
+     */
+    maxBufferBytes?: number;
+    /**
+     * Milliseconds before the spawned process is killed with SIGTERM and the
+     * promise is rejected.
+     * @defaultValue `30000`
+     */
+    timeoutMs?: number;
+}
+/**
+ * Synthesised audio returned by {@link PiperTTSProvider.synthesize}.
+ */
+export interface SynthesisResult {
+    /** Raw WAV audio bytes produced by Piper. */
+    audioBuffer: Buffer;
+    /** MIME type of the audio data. Always `'audio/wav'` for this provider. */
+    mimeType: 'audio/wav';
+    /** Billable cost (always 0 — fully local). */
+    cost: 0;
+}
+/**
+ * Piper offline 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 PiperTTSProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    readonly id = "piper";
+    /**
+     * Streaming is not supported — Piper outputs a complete WAV file.
+     * Setting this to `false` signals the pipeline to use batch mode.
+     */
+    readonly supportsStreaming = false;
+    private readonly _binaryPath;
+    private readonly _modelPath;
+    private readonly _maxBufferBytes;
+    private readonly _timeoutMs;
+    /**
+     * Create a new {@link PiperTTSProvider}.
+     *
+     * @param options - Optional configuration.  All fields have sensible defaults
+     *   or fall back to environment variables.
+     */
+    constructor(options?: PiperTTSProviderOptions);
+    /**
+     * Synthesise plain text to WAV audio using the local Piper binary.
+     *
+     * Piper is invoked as:
+     * ```
+     * piper --model <modelPath> --output_file -
+     * ```
+     * The text is written to `stdin`; WAV bytes are read from `stdout`.
+     *
+     * @param text - Plain text to synthesise.
+     * @returns {@link SynthesisResult} containing the raw WAV buffer.
+     * @throws If Piper exits with a non-zero code, times out, or the buffer
+     *   limit is exceeded.
+     */
+    synthesize(text: string): Promise<SynthesisResult>;
+    /** Returns the resolved binary path. */
+    getBinaryPath(): string;
+    /** Returns the resolved model path. */
+    getModelPath(): string;
+    /** Returns the configured max buffer size in bytes. */
+    getMaxBufferBytes(): number;
+    /** Returns the configured timeout in milliseconds. */
+    getTimeoutMs(): number;
+}
+//# sourceMappingURL=PiperTTSProvider.d.ts.map

package/dist/PiperTTSProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PiperTTSProvider.d.ts","sourceRoot":"","sources":["../src/PiperTTSProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,WAAW,CAAC;IACtB,8CAA8C;IAC9C,IAAI,EAAE,CAAC,CAAC;CACT;AAMD;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,WAAW;IAEtB;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,SAAS;IAEnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC;;;;;OAKG;gBACS,OAAO,GAAE,uBAA4B;IAcjD;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA0ExD,wCAAwC;IACxC,aAAa,IAAI,MAAM;IAEvB,uCAAuC;IACvC,YAAY,IAAI,MAAM;IAEtB,uDAAuD;IACvD,iBAAiB,IAAI,MAAM;IAE3B,sDAAsD;IACtD,YAAY,IAAI,MAAM;CACvB"}

package/dist/PiperTTSProvider.js

@@ -0,0 +1,143 @@
+/**
+ * @file PiperTTSProvider.ts
+ * @description Offline text-to-speech provider that invokes the Piper binary.
+ *
+ * [Piper](https://github.com/rhasspy/piper) is a fast, local neural TTS
+ * system.  This provider spawns the binary via `child_process.spawn`, writes
+ * the input text to `stdin`, and collects the WAV audio written to `stdout`.
+ *
+ * No npm dependencies are required beyond Node's built-in `child_process`
+ * module.  The Piper binary must be installed separately and be accessible
+ * via the `binaryPath` option or the `PIPER_BIN` environment variable
+ * (defaults to `piper`, which expects the binary to be on `PATH`).
+ *
+ * @module piper
+ */
+import { spawn } from 'child_process';
+import os from 'os';
+import path from 'path';
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+/**
+ * Piper offline 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 PiperTTSProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    id = 'piper';
+    /**
+     * Streaming is not supported — Piper outputs a complete WAV file.
+     * Setting this to `false` signals the pipeline to use batch mode.
+     */
+    supportsStreaming = false;
+    _binaryPath;
+    _modelPath;
+    _maxBufferBytes;
+    _timeoutMs;
+    /**
+     * Create a new {@link PiperTTSProvider}.
+     *
+     * @param options - Optional configuration.  All fields have sensible defaults
+     *   or fall back to environment variables.
+     */
+    constructor(options = {}) {
+        this._binaryPath = options.binaryPath ?? process.env['PIPER_BIN'] ?? 'piper';
+        this._modelPath =
+            options.modelPath ??
+                process.env['PIPER_MODEL_PATH'] ??
+                path.join(os.homedir(), '.agentos', 'models', 'piper', 'en_US-lessac-medium.onnx');
+        this._maxBufferBytes = options.maxBufferBytes ?? 10 * 1024 * 1024; // 10 MB
+        this._timeoutMs = options.timeoutMs ?? 30_000;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Synthesise plain text to WAV audio using the local Piper binary.
+     *
+     * Piper is invoked as:
+     * ```
+     * piper --model <modelPath> --output_file -
+     * ```
+     * The text is written to `stdin`; WAV bytes are read from `stdout`.
+     *
+     * @param text - Plain text to synthesise.
+     * @returns {@link SynthesisResult} containing the raw WAV buffer.
+     * @throws If Piper exits with a non-zero code, times out, or the buffer
+     *   limit is exceeded.
+     */
+    async synthesize(text) {
+        return new Promise((resolve, reject) => {
+            const proc = spawn(this._binaryPath, [
+                '--model', this._modelPath,
+                '--output_file', '-',
+            ]);
+            const chunks = [];
+            let totalBytes = 0;
+            let settled = false;
+            /** Settle the promise once, ignoring subsequent events. */
+            const settle = (err, result) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (err) {
+                    proc.kill('SIGTERM');
+                    reject(err);
+                }
+                else {
+                    resolve(result);
+                }
+            };
+            // Timeout guard.
+            const timer = setTimeout(() => {
+                settle(new Error(`Piper process timed out after ${this._timeoutMs} ms`));
+            }, this._timeoutMs);
+            proc.stdout.on('data', (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes > this._maxBufferBytes) {
+                    settle(new Error(`Piper output exceeded maxBufferBytes limit (${this._maxBufferBytes} bytes)`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            proc.stderr.on('data', (chunk) => {
+                // Piper writes progress/info to stderr; capture for error reporting.
+                // We do NOT reject on stderr data alone — only on non-zero exit.
+                void chunk; // intentionally unused unless exit code is non-zero
+            });
+            proc.on('error', (err) => {
+                settle(new Error(`Failed to spawn Piper binary "${this._binaryPath}": ${err.message}`));
+            });
+            proc.on('close', (code) => {
+                if (code !== 0 && code !== null) {
+                    settle(new Error(`Piper exited with non-zero code ${code}`));
+                    return;
+                }
+                settle(null, {
+                    audioBuffer: Buffer.concat(chunks),
+                    mimeType: 'audio/wav',
+                    cost: 0,
+                });
+            });
+            // Write text to stdin and close the stream so Piper knows input is done.
+            proc.stdin.write(text);
+            proc.stdin.end();
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Accessors (for testing / diagnostics)
+    // ---------------------------------------------------------------------------
+    /** Returns the resolved binary path. */
+    getBinaryPath() { return this._binaryPath; }
+    /** Returns the resolved model path. */
+    getModelPath() { return this._modelPath; }
+    /** Returns the configured max buffer size in bytes. */
+    getMaxBufferBytes() { return this._maxBufferBytes; }
+    /** Returns the configured timeout in milliseconds. */
+    getTimeoutMs() { return this._timeoutMs; }
+}
+//# sourceMappingURL=PiperTTSProvider.js.map

package/dist/PiperTTSProvider.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Piper TTS extension pack.
+ *
+ * Exports the main {@link createPiperTTS} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPiperTTS } from '@framers/agentos-ext-piper';
+ *
+ * const tts = createPiperTTS({ modelPath: '/opt/piper/en_US-lessac-medium.onnx' });
+ * const { audioBuffer } = await tts.synthesize('Hello world');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-piper" }] }
+ * ```
+ *
+ * @module piper
+ */
+import { PiperTTSProvider } from './PiperTTSProvider.js';
+import type { PiperTTSProviderOptions } from './PiperTTSProvider.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 PiperTTSProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link PiperTTSProvider}.
+ */
+export declare function createPiperTTS(options?: PiperTTSProviderOptions): PiperTTSProvider;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link PiperTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export { PiperTTSProvider } from './PiperTTSProvider.js';
+export type { SynthesisResult, PiperTTSProviderOptions } from './PiperTTSProvider.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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAMrE,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,cAAc,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,gBAAgB,CAElF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAqBhF;AAMD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,74 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Piper TTS extension pack.
+ *
+ * Exports the main {@link createPiperTTS} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPiperTTS } from '@framers/agentos-ext-piper';
+ *
+ * const tts = createPiperTTS({ modelPath: '/opt/piper/en_US-lessac-medium.onnx' });
+ * const { audioBuffer } = await tts.synthesize('Hello world');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-piper" }] }
+ * ```
+ *
+ * @module piper
+ */
+import { PiperTTSProvider } from './PiperTTSProvider.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_TTS = 'tts-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link PiperTTSProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link PiperTTSProvider}.
+ */
+export function createPiperTTS(options) {
+    return new PiperTTSProvider(options);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link PiperTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const opts = context.options ?? {};
+    const provider = new PiperTTSProvider({
+        binaryPath: opts['binaryPath'],
+        modelPath: opts['modelPath'],
+        maxBufferBytes: opts['maxBufferBytes'],
+        timeoutMs: opts['timeoutMs'],
+    });
+    return {
+        id: 'piper',
+        descriptors: [
+            {
+                id: 'piper',
+                kind: EXTENSION_KIND_TTS,
+                payload: provider,
+                enableByDefault: true,
+                metadata: { providerId: 'piper' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { PiperTTSProvider } from './PiperTTSProvider.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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA4BzD,uEAAuE;AACvE,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAAiC;IAC9D,OAAO,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC;QACpC,UAAU,EAAE,IAAI,CAAC,YAAY,CAAuB;QACpD,SAAS,EAAE,IAAI,CAAC,WAAW,CAAuB;QAClD,cAAc,EAAE,IAAI,CAAC,gBAAgB,CAAuB;QAC5D,SAAS,EAAE,IAAI,CAAC,WAAW,CAAuB;KACnD,CAAC,CAAC;IAEH,OAAO;QACL,EAAE,EAAE,OAAO;QACX,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,OAAO;gBACX,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,QAAQ;gBACjB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE;aAClC;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-piper",
+  "version": "0.1.0",
+  "description": "Offline text-to-speech via Piper binary",
+  "kind": "tts-provider",
+  "extensionId": "piper",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@framers/agentos-ext-piper",
+  "version": "0.2.0",
+  "description": "Offline text-to-speech via Piper binary 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"
+  },
+  "devDependencies": {
+    "@types/node": "^20.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/piper"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/PiperTTSProvider.ts

@@ -0,0 +1,214 @@
+/**
+ * @file PiperTTSProvider.ts
+ * @description Offline text-to-speech provider that invokes the Piper binary.
+ *
+ * [Piper](https://github.com/rhasspy/piper) is a fast, local neural TTS
+ * system.  This provider spawns the binary via `child_process.spawn`, writes
+ * the input text to `stdin`, and collects the WAV audio written to `stdout`.
+ *
+ * No npm dependencies are required beyond Node's built-in `child_process`
+ * module.  The Piper binary must be installed separately and be accessible
+ * via the `binaryPath` option or the `PIPER_BIN` environment variable
+ * (defaults to `piper`, which expects the binary to be on `PATH`).
+ *
+ * @module piper
+ */
+
+import { spawn } from 'child_process';
+import os from 'os';
+import path from 'path';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Constructor options for {@link PiperTTSProvider}.
+ */
+export interface PiperTTSProviderOptions {
+  /**
+   * Absolute path to the Piper executable, or just `'piper'` if it is on
+   * `PATH`.  Resolved from `PIPER_BIN` env var when omitted.
+   * @defaultValue `process.env.PIPER_BIN ?? 'piper'`
+   */
+  binaryPath?: string;
+
+  /**
+   * Absolute path to the ONNX voice model file.
+   * Resolved from `PIPER_MODEL_PATH` env var when omitted.
+   * @defaultValue `~/.agentos/models/piper/en_US-lessac-medium.onnx`
+   */
+  modelPath?: string;
+
+  /**
+   * Maximum number of bytes accepted from Piper's stdout.
+   * Prevents runaway memory usage if the binary misbehaves.
+   * @defaultValue `10485760` (10 MB)
+   */
+  maxBufferBytes?: number;
+
+  /**
+   * Milliseconds before the spawned process is killed with SIGTERM and the
+   * promise is rejected.
+   * @defaultValue `30000`
+   */
+  timeoutMs?: number;
+}
+
+/**
+ * Synthesised audio returned by {@link PiperTTSProvider.synthesize}.
+ */
+export interface SynthesisResult {
+  /** Raw WAV audio bytes produced by Piper. */
+  audioBuffer: Buffer;
+  /** MIME type of the audio data. Always `'audio/wav'` for this provider. */
+  mimeType: 'audio/wav';
+  /** Billable cost (always 0 — fully local). */
+  cost: 0;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Piper offline 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 PiperTTSProvider {
+  /** Stable provider identifier used by the AgentOS extension registry. */
+  readonly id = 'piper';
+
+  /**
+   * Streaming is not supported — Piper outputs a complete WAV file.
+   * Setting this to `false` signals the pipeline to use batch mode.
+   */
+  readonly supportsStreaming = false;
+
+  private readonly _binaryPath: string;
+  private readonly _modelPath: string;
+  private readonly _maxBufferBytes: number;
+  private readonly _timeoutMs: number;
+
+  /**
+   * Create a new {@link PiperTTSProvider}.
+   *
+   * @param options - Optional configuration.  All fields have sensible defaults
+   *   or fall back to environment variables.
+   */
+  constructor(options: PiperTTSProviderOptions = {}) {
+    this._binaryPath = options.binaryPath ?? process.env['PIPER_BIN'] ?? 'piper';
+    this._modelPath =
+      options.modelPath ??
+      process.env['PIPER_MODEL_PATH'] ??
+      path.join(os.homedir(), '.agentos', 'models', 'piper', 'en_US-lessac-medium.onnx');
+    this._maxBufferBytes = options.maxBufferBytes ?? 10 * 1024 * 1024; // 10 MB
+    this._timeoutMs = options.timeoutMs ?? 30_000;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Synthesise plain text to WAV audio using the local Piper binary.
+   *
+   * Piper is invoked as:
+   * ```
+   * piper --model <modelPath> --output_file -
+   * ```
+   * The text is written to `stdin`; WAV bytes are read from `stdout`.
+   *
+   * @param text - Plain text to synthesise.
+   * @returns {@link SynthesisResult} containing the raw WAV buffer.
+   * @throws If Piper exits with a non-zero code, times out, or the buffer
+   *   limit is exceeded.
+   */
+  async synthesize(text: string): Promise<SynthesisResult> {
+    return new Promise<SynthesisResult>((resolve, reject) => {
+      const proc = spawn(this._binaryPath, [
+        '--model', this._modelPath,
+        '--output_file', '-',
+      ]);
+
+      const chunks: Buffer[] = [];
+      let totalBytes = 0;
+      let settled = false;
+
+      /** Settle the promise once, ignoring subsequent events. */
+      const settle = (err: Error | null, result?: SynthesisResult) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (err) {
+          proc.kill('SIGTERM');
+          reject(err);
+        } else {
+          resolve(result!);
+        }
+      };
+
+      // Timeout guard.
+      const timer = setTimeout(() => {
+        settle(new Error(`Piper process timed out after ${this._timeoutMs} ms`));
+      }, this._timeoutMs);
+
+      proc.stdout.on('data', (chunk: Buffer) => {
+        totalBytes += chunk.length;
+        if (totalBytes > this._maxBufferBytes) {
+          settle(
+            new Error(
+              `Piper output exceeded maxBufferBytes limit (${this._maxBufferBytes} bytes)`,
+            ),
+          );
+          return;
+        }
+        chunks.push(chunk);
+      });
+
+      proc.stderr.on('data', (chunk: Buffer) => {
+        // Piper writes progress/info to stderr; capture for error reporting.
+        // We do NOT reject on stderr data alone — only on non-zero exit.
+        void chunk; // intentionally unused unless exit code is non-zero
+      });
+
+      proc.on('error', (err: Error) => {
+        settle(new Error(`Failed to spawn Piper binary "${this._binaryPath}": ${err.message}`));
+      });
+
+      proc.on('close', (code: number | null) => {
+        if (code !== 0 && code !== null) {
+          settle(new Error(`Piper exited with non-zero code ${code}`));
+          return;
+        }
+        settle(null, {
+          audioBuffer: Buffer.concat(chunks),
+          mimeType: 'audio/wav',
+          cost: 0,
+        });
+      });
+
+      // Write text to stdin and close the stream so Piper knows input is done.
+      proc.stdin.write(text);
+      proc.stdin.end();
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Accessors (for testing / diagnostics)
+  // ---------------------------------------------------------------------------
+
+  /** Returns the resolved binary path. */
+  getBinaryPath(): string { return this._binaryPath; }
+
+  /** Returns the resolved model path. */
+  getModelPath(): string { return this._modelPath; }
+
+  /** Returns the configured max buffer size in bytes. */
+  getMaxBufferBytes(): number { return this._maxBufferBytes; }
+
+  /** Returns the configured timeout in milliseconds. */
+  getTimeoutMs(): number { return this._timeoutMs; }
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Piper TTS extension pack.
+ *
+ * Exports the main {@link createPiperTTS} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPiperTTS } from '@framers/agentos-ext-piper';
+ *
+ * const tts = createPiperTTS({ modelPath: '/opt/piper/en_US-lessac-medium.onnx' });
+ * const { audioBuffer } = await tts.synthesize('Hello world');
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-piper" }] }
+ * ```
+ *
+ * @module piper
+ */
+
+import { PiperTTSProvider } from './PiperTTSProvider.js';
+import type { PiperTTSProviderOptions } from './PiperTTSProvider.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 PiperTTSProvider} instance.
+ *
+ * @param options - Optional constructor options.
+ * @returns Configured {@link PiperTTSProvider}.
+ */
+export function createPiperTTS(options?: PiperTTSProviderOptions): PiperTTSProvider {
+  return new PiperTTSProvider(options);
+}
+
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads optional configuration from the context `options` map and returns an
+ * {@link ExtensionPack} containing a single `tts-provider` descriptor backed
+ * by {@link PiperTTSProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  const opts = context.options ?? {};
+  const provider = new PiperTTSProvider({
+    binaryPath: opts['binaryPath'] as string | undefined,
+    modelPath: opts['modelPath'] as string | undefined,
+    maxBufferBytes: opts['maxBufferBytes'] as number | undefined,
+    timeoutMs: opts['timeoutMs'] as number | undefined,
+  });
+
+  return {
+    id: 'piper',
+    descriptors: [
+      {
+        id: 'piper',
+        kind: EXTENSION_KIND_TTS,
+        payload: provider,
+        enableByDefault: true,
+        metadata: { providerId: 'piper' },
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { PiperTTSProvider } from './PiperTTSProvider.js';
+export type { SynthesisResult, PiperTTSProviderOptions } from './PiperTTSProvider.js';