@framers/agentos-ext-porcupine 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,16 @@
+# porcupine — Wake-Word Extension Pack
+
+Provides wake-word detection via the [Picovoice Porcupine](https://picovoice.ai/platform/porcupine/) engine.
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `accessKey` | **Required.** Picovoice access key from [console.picovoice.ai](https://console.picovoice.ai/) |
+| `keywords` | Array of built-in keyword names (e.g. `['porcupine', 'bumblebee']`) |
+| `sensitivities` | Per-keyword detection sensitivity in [0, 1] (default 0.5 each) |
+
+## Features
+- On-device, privacy-preserving detection (no audio sent to cloud)
+- Stateless per-frame processing
+- Configurable sensitivity per keyword

package/dist/PorcupineWakeWordProvider.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file PorcupineWakeWordProvider.ts
+ * @description Wake-word detection provider backed by Picovoice Porcupine.
+ *
+ * [Porcupine](https://picovoice.ai/platform/porcupine/) is an on-device
+ * wake-word engine.  This provider wraps `@picovoice/porcupine-node` and
+ * exposes the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline.
+ *
+ * The `@picovoice/porcupine-node` package is declared as a peer dependency so
+ * it is loaded only at runtime via dynamic `import()`.
+ *
+ * ### Threading model
+ * Porcupine's `process()` method is synchronous and stateless per-frame — each
+ * 512-sample frame is processed independently.  The provider is therefore safe
+ * to call from any async context.
+ *
+ * @module porcupine
+ */
+/**
+ * A detected wake-word event returned by {@link PorcupineWakeWordProvider.detect}.
+ */
+export interface WakeWordDetection {
+    /** The keyword string that was detected (e.g. `'porcupine'`). */
+    keyword: string;
+    /**
+     * Confidence score.  Porcupine does not expose a per-detection confidence;
+     * this is always `1.0` to signal a positive detection.
+     */
+    confidence: 1.0;
+    /** Stable provider identifier. */
+    providerId: 'porcupine';
+}
+/**
+ * Constructor options for {@link PorcupineWakeWordProvider}.
+ */
+export interface PorcupineWakeWordProviderOptions {
+    /** Picovoice access key from https://console.picovoice.ai/ */
+    accessKey: string;
+    /**
+     * Built-in keyword names to detect (e.g. `['porcupine', 'bumblebee']`).
+     * @defaultValue `['porcupine']`
+     */
+    keywords?: string[];
+    /**
+     * Detection sensitivity in [0, 1] for each keyword.
+     * Must be the same length as `keywords` when provided.
+     * @defaultValue `[0.5]` (or `0.5` per keyword)
+     */
+    sensitivities?: number[];
+}
+/**
+ * Picovoice Porcupine wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export declare class PorcupineWakeWordProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    readonly id = "porcupine";
+    private readonly _accessKey;
+    private readonly _keywords;
+    private readonly _sensitivities;
+    /** Lazily initialised Porcupine instance. */
+    private _porcupine;
+    /**
+     * Create a new {@link PorcupineWakeWordProvider}.
+     *
+     * @param options - Configuration including the required Picovoice access key.
+     */
+    constructor(options: PorcupineWakeWordProviderOptions);
+    /**
+     * Lazily initialise the Porcupine engine on first use.
+     *
+     * Dynamic import keeps the peer dep truly optional at module-load time.
+     */
+    private _getPorcupine;
+    /**
+     * Process a single audio frame and detect any wake-word.
+     *
+     * Each frame must be exactly 512 samples of 16-bit PCM at 16 kHz (the
+     * Porcupine frame length).  `sampleRate` is accepted for interface
+     * compatibility but Porcupine always operates at 16 kHz.
+     *
+     * @param frame      - 16-bit PCM audio frame as an `Int16Array` (512 samples).
+     * @param sampleRate - Sample rate (informational; must be 16000 for Porcupine).
+     * @returns A {@link WakeWordDetection} when a keyword is detected, or `null`.
+     */
+    detect(frame: Int16Array, _sampleRate: number): Promise<WakeWordDetection | null>;
+    /**
+     * No-op reset.
+     *
+     * Porcupine processes frames statelessly; there is no internal buffer to
+     * flush.  This method exists for interface compatibility.
+     */
+    reset(): void;
+    /**
+     * Release the native Porcupine engine resources.
+     *
+     * Call this when the provider is no longer needed to free memory held by
+     * the native addon.
+     */
+    dispose(): Promise<void>;
+    /** Returns the configured keyword list. */
+    getKeywords(): string[];
+    /** Returns the configured sensitivity list. */
+    getSensitivities(): number[];
+}
+//# sourceMappingURL=PorcupineWakeWordProvider.d.ts.map

package/dist/PorcupineWakeWordProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PorcupineWakeWordProvider.d.ts","sourceRoot":"","sources":["../src/PorcupineWakeWordProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,EAAE,GAAG,CAAC;IAChB,kCAAkC;IAClC,UAAU,EAAE,WAAW,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,gCAAgC;IAC/C,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,qBAAa,yBAAyB;IACpC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe;IAE1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAW;IAE1C,6CAA6C;IAE7C,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;OAIG;gBACS,OAAO,EAAE,gCAAgC;IAWrD;;;;OAIG;YAEW,aAAa;IAgB3B;;;;;;;;;;OAUG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgBvF;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,2CAA2C;IAC3C,WAAW,IAAI,MAAM,EAAE;IAEvB,+CAA+C;IAC/C,gBAAgB,IAAI,MAAM,EAAE;CAC7B"}

package/dist/PorcupineWakeWordProvider.js

@@ -0,0 +1,121 @@
+/**
+ * @file PorcupineWakeWordProvider.ts
+ * @description Wake-word detection provider backed by Picovoice Porcupine.
+ *
+ * [Porcupine](https://picovoice.ai/platform/porcupine/) is an on-device
+ * wake-word engine.  This provider wraps `@picovoice/porcupine-node` and
+ * exposes the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline.
+ *
+ * The `@picovoice/porcupine-node` package is declared as a peer dependency so
+ * it is loaded only at runtime via dynamic `import()`.
+ *
+ * ### Threading model
+ * Porcupine's `process()` method is synchronous and stateless per-frame — each
+ * 512-sample frame is processed independently.  The provider is therefore safe
+ * to call from any async context.
+ *
+ * @module porcupine
+ */
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+/**
+ * Picovoice Porcupine wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class PorcupineWakeWordProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    id = 'porcupine';
+    _accessKey;
+    _keywords;
+    _sensitivities;
+    /** Lazily initialised Porcupine instance. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _porcupine = null;
+    /**
+     * Create a new {@link PorcupineWakeWordProvider}.
+     *
+     * @param options - Configuration including the required Picovoice access key.
+     */
+    constructor(options) {
+        this._accessKey = options.accessKey;
+        this._keywords = options.keywords ?? ['porcupine'];
+        this._sensitivities =
+            options.sensitivities ?? this._keywords.map(() => 0.5);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Lazily initialise the Porcupine engine on first use.
+     *
+     * Dynamic import keeps the peer dep truly optional at module-load time.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async _getPorcupine() {
+        if (!this._porcupine) {
+            const { Porcupine } = await import('@picovoice/porcupine-node');
+            this._porcupine = new Porcupine(this._accessKey, this._keywords, this._sensitivities);
+        }
+        return this._porcupine;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Process a single audio frame and detect any wake-word.
+     *
+     * Each frame must be exactly 512 samples of 16-bit PCM at 16 kHz (the
+     * Porcupine frame length).  `sampleRate` is accepted for interface
+     * compatibility but Porcupine always operates at 16 kHz.
+     *
+     * @param frame      - 16-bit PCM audio frame as an `Int16Array` (512 samples).
+     * @param sampleRate - Sample rate (informational; must be 16000 for Porcupine).
+     * @returns A {@link WakeWordDetection} when a keyword is detected, or `null`.
+     */
+    async detect(frame, _sampleRate) {
+        const porcupine = await this._getPorcupine();
+        const keywordIndex = porcupine.process(frame);
+        if (keywordIndex < 0) {
+            // No detection.
+            return null;
+        }
+        return {
+            keyword: this._keywords[keywordIndex] ?? String(keywordIndex),
+            confidence: 1.0,
+            providerId: 'porcupine',
+        };
+    }
+    /**
+     * No-op reset.
+     *
+     * Porcupine processes frames statelessly; there is no internal buffer to
+     * flush.  This method exists for interface compatibility.
+     */
+    reset() {
+        // Intentional no-op — Porcupine is stateless per frame.
+    }
+    /**
+     * Release the native Porcupine engine resources.
+     *
+     * Call this when the provider is no longer needed to free memory held by
+     * the native addon.
+     */
+    async dispose() {
+        if (this._porcupine) {
+            this._porcupine.release();
+            this._porcupine = null;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Accessors (for testing / diagnostics)
+    // ---------------------------------------------------------------------------
+    /** Returns the configured keyword list. */
+    getKeywords() { return [...this._keywords]; }
+    /** Returns the configured sensitivity list. */
+    getSensitivities() { return [...this._sensitivities]; }
+}
+//# sourceMappingURL=PorcupineWakeWordProvider.js.map

package/dist/PorcupineWakeWordProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PorcupineWakeWordProvider.js","sourceRoot":"","sources":["../src/PorcupineWakeWordProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAwCH,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,OAAO,yBAAyB;IACpC,yEAAyE;IAChE,EAAE,GAAG,WAAW,CAAC;IAET,UAAU,CAAS;IACnB,SAAS,CAAW;IACpB,cAAc,CAAW;IAE1C,6CAA6C;IAC7C,8DAA8D;IACtD,UAAU,GAAe,IAAI,CAAC;IAEtC;;;;OAIG;IACH,YAAY,OAAyC;QACnD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,cAAc;YACjB,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3D,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;OAIG;IACH,8DAA8D;IACtD,KAAK,CAAC,aAAa;QACzB,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;YAChE,IAAI,CAAC,UAAU,GAAG,IAAI,SAAS,CAC7B,IAAI,CAAC,UAAU,EACf,IAAI,CAAC,SAAS,EACd,IAAI,CAAC,cAAc,CACpB,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAM,CAAC,KAAiB,EAAE,WAAmB;QACjD,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE,CAAC;QAC7C,MAAM,YAAY,GAAW,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAEtD,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,gBAAgB;YAChB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,MAAM,CAAC,YAAY,CAAC;YAC7D,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,WAAW;SACxB,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK;QACH,wDAAwD;IAC1D,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACzB,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,wCAAwC;IACxC,8EAA8E;IAE9E,2CAA2C;IAC3C,WAAW,KAAe,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAEvD,+CAA+C;IAC/C,gBAAgB,KAAe,OAAO,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;CAClE"}

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Porcupine wake-word extension pack.
+ *
+ * Exports the main {@link createPorcupine} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPorcupine } from '@framers/agentos-ext-porcupine';
+ *
+ * const wakeWord = createPorcupine({ accessKey: 'YOUR_KEY', keywords: ['porcupine'] });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-porcupine" }] }
+ * ```
+ *
+ * @module porcupine
+ */
+import { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.js';
+import type { PorcupineWakeWordProviderOptions } from './PorcupineWakeWordProvider.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 PorcupineWakeWordProvider} instance.
+ *
+ * @param options - Constructor options (access key required).
+ * @returns Configured {@link PorcupineWakeWordProvider}.
+ */
+export declare function createPorcupine(options: PorcupineWakeWordProviderOptions): PorcupineWakeWordProvider;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `PICOVOICE_ACCESS_KEY` secret and optional keyword configuration
+ * from the context, and returns an {@link ExtensionPack} containing a single
+ * `wake-word-provider` descriptor.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.js';
+export type { WakeWordDetection, PorcupineWakeWordProviderOptions, } from './PorcupineWakeWordProvider.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,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,gCAAgC,CAAC;AAMvF,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,eAAe,CAC7B,OAAO,EAAE,gCAAgC,GACxC,yBAAyB,CAE3B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAoBhF;AAMD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,YAAY,EACV,iBAAiB,EACjB,gCAAgC,GACjC,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,72 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Porcupine wake-word extension pack.
+ *
+ * Exports the main {@link createPorcupine} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPorcupine } from '@framers/agentos-ext-porcupine';
+ *
+ * const wakeWord = createPorcupine({ accessKey: 'YOUR_KEY', keywords: ['porcupine'] });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-porcupine" }] }
+ * ```
+ *
+ * @module porcupine
+ */
+import { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_WAKE_WORD = 'wake-word-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link PorcupineWakeWordProvider} instance.
+ *
+ * @param options - Constructor options (access key required).
+ * @returns Configured {@link PorcupineWakeWordProvider}.
+ */
+export function createPorcupine(options) {
+    return new PorcupineWakeWordProvider(options);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `PICOVOICE_ACCESS_KEY` secret and optional keyword configuration
+ * from the context, and returns an {@link ExtensionPack} containing a single
+ * `wake-word-provider` descriptor.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const accessKey = context.getSecret?.('PICOVOICE_ACCESS_KEY') ?? '';
+    const opts = context.options ?? {};
+    const keywords = opts['keywords'];
+    const sensitivities = opts['sensitivities'];
+    const provider = new PorcupineWakeWordProvider({ accessKey, keywords, sensitivities });
+    return {
+        id: 'porcupine',
+        descriptors: [
+            {
+                id: 'porcupine',
+                kind: EXTENSION_KIND_WAKE_WORD,
+                payload: provider,
+                enableByDefault: true,
+                metadata: { providerId: 'porcupine' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.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,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AA4B3E,uEAAuE;AACvE,MAAM,wBAAwB,GAAG,oBAAoB,CAAC;AAEtD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAyC;IAEzC,OAAO,IAAI,yBAAyB,CAAC,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC;IACpE,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAyB,CAAC;IAC1D,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,CAAyB,CAAC;IAEpE,MAAM,QAAQ,GAAG,IAAI,yBAAyB,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,CAAC;IAEvF,OAAO;QACL,EAAE,EAAE,WAAW;QACf,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,WAAW;gBACf,IAAI,EAAE,wBAAwB;gBAC9B,OAAO,EAAE,QAAQ;gBACjB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,WAAW,EAAE;aACtC;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-porcupine",
+  "version": "0.1.0",
+  "description": "Wake-word detection via Picovoice Porcupine",
+  "kind": "wake-word-provider",
+  "extensionId": "porcupine",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@framers/agentos-ext-porcupine",
+  "version": "0.2.0",
+  "description": "Wake-word detection via Picovoice Porcupine 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",
+    "@picovoice/porcupine-node": "^3.0.0"
+  },
+  "devDependencies": {
+    "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/porcupine"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/PorcupineWakeWordProvider.ts

@@ -0,0 +1,178 @@
+/**
+ * @file PorcupineWakeWordProvider.ts
+ * @description Wake-word detection provider backed by Picovoice Porcupine.
+ *
+ * [Porcupine](https://picovoice.ai/platform/porcupine/) is an on-device
+ * wake-word engine.  This provider wraps `@picovoice/porcupine-node` and
+ * exposes the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline.
+ *
+ * The `@picovoice/porcupine-node` package is declared as a peer dependency so
+ * it is loaded only at runtime via dynamic `import()`.
+ *
+ * ### Threading model
+ * Porcupine's `process()` method is synchronous and stateless per-frame — each
+ * 512-sample frame is processed independently.  The provider is therefore safe
+ * to call from any async context.
+ *
+ * @module porcupine
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * A detected wake-word event returned by {@link PorcupineWakeWordProvider.detect}.
+ */
+export interface WakeWordDetection {
+  /** The keyword string that was detected (e.g. `'porcupine'`). */
+  keyword: string;
+  /**
+   * Confidence score.  Porcupine does not expose a per-detection confidence;
+   * this is always `1.0` to signal a positive detection.
+   */
+  confidence: 1.0;
+  /** Stable provider identifier. */
+  providerId: 'porcupine';
+}
+
+/**
+ * Constructor options for {@link PorcupineWakeWordProvider}.
+ */
+export interface PorcupineWakeWordProviderOptions {
+  /** Picovoice access key from https://console.picovoice.ai/ */
+  accessKey: string;
+  /**
+   * Built-in keyword names to detect (e.g. `['porcupine', 'bumblebee']`).
+   * @defaultValue `['porcupine']`
+   */
+  keywords?: string[];
+  /**
+   * Detection sensitivity in [0, 1] for each keyword.
+   * Must be the same length as `keywords` when provided.
+   * @defaultValue `[0.5]` (or `0.5` per keyword)
+   */
+  sensitivities?: number[];
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Picovoice Porcupine wake-word provider.
+ *
+ * Implements the `WakeWordProvider` contract expected by the AgentOS voice
+ * pipeline without taking a hard runtime dependency on the interface types.
+ */
+export class PorcupineWakeWordProvider {
+  /** Stable provider identifier used by the AgentOS extension registry. */
+  readonly id = 'porcupine';
+
+  private readonly _accessKey: string;
+  private readonly _keywords: string[];
+  private readonly _sensitivities: number[];
+
+  /** Lazily initialised Porcupine instance. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private _porcupine: any | null = null;
+
+  /**
+   * Create a new {@link PorcupineWakeWordProvider}.
+   *
+   * @param options - Configuration including the required Picovoice access key.
+   */
+  constructor(options: PorcupineWakeWordProviderOptions) {
+    this._accessKey = options.accessKey;
+    this._keywords = options.keywords ?? ['porcupine'];
+    this._sensitivities =
+      options.sensitivities ?? this._keywords.map(() => 0.5);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Lazily initialise the Porcupine engine on first use.
+   *
+   * Dynamic import keeps the peer dep truly optional at module-load time.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private async _getPorcupine(): Promise<any> {
+    if (!this._porcupine) {
+      const { Porcupine } = await import('@picovoice/porcupine-node');
+      this._porcupine = new Porcupine(
+        this._accessKey,
+        this._keywords,
+        this._sensitivities,
+      );
+    }
+    return this._porcupine;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Process a single audio frame and detect any wake-word.
+   *
+   * Each frame must be exactly 512 samples of 16-bit PCM at 16 kHz (the
+   * Porcupine frame length).  `sampleRate` is accepted for interface
+   * compatibility but Porcupine always operates at 16 kHz.
+   *
+   * @param frame      - 16-bit PCM audio frame as an `Int16Array` (512 samples).
+   * @param sampleRate - Sample rate (informational; must be 16000 for Porcupine).
+   * @returns A {@link WakeWordDetection} when a keyword is detected, or `null`.
+   */
+  async detect(frame: Int16Array, _sampleRate: number): Promise<WakeWordDetection | null> {
+    const porcupine = await this._getPorcupine();
+    const keywordIndex: number = porcupine.process(frame);
+
+    if (keywordIndex < 0) {
+      // No detection.
+      return null;
+    }
+
+    return {
+      keyword: this._keywords[keywordIndex] ?? String(keywordIndex),
+      confidence: 1.0,
+      providerId: 'porcupine',
+    };
+  }
+
+  /**
+   * No-op reset.
+   *
+   * Porcupine processes frames statelessly; there is no internal buffer to
+   * flush.  This method exists for interface compatibility.
+   */
+  reset(): void {
+    // Intentional no-op — Porcupine is stateless per frame.
+  }
+
+  /**
+   * Release the native Porcupine engine resources.
+   *
+   * Call this when the provider is no longer needed to free memory held by
+   * the native addon.
+   */
+  async dispose(): Promise<void> {
+    if (this._porcupine) {
+      this._porcupine.release();
+      this._porcupine = null;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Accessors (for testing / diagnostics)
+  // ---------------------------------------------------------------------------
+
+  /** Returns the configured keyword list. */
+  getKeywords(): string[] { return [...this._keywords]; }
+
+  /** Returns the configured sensitivity list. */
+  getSensitivities(): number[] { return [...this._sensitivities]; }
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Porcupine wake-word extension pack.
+ *
+ * Exports the main {@link createPorcupine} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createPorcupine } from '@framers/agentos-ext-porcupine';
+ *
+ * const wakeWord = createPorcupine({ accessKey: 'YOUR_KEY', keywords: ['porcupine'] });
+ * const detection = await wakeWord.detect(frame, 16000);
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-porcupine" }] }
+ * ```
+ *
+ * @module porcupine
+ */
+
+import { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.js';
+import type { PorcupineWakeWordProviderOptions } from './PorcupineWakeWordProvider.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_WAKE_WORD = 'wake-word-provider';
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a standalone {@link PorcupineWakeWordProvider} instance.
+ *
+ * @param options - Constructor options (access key required).
+ * @returns Configured {@link PorcupineWakeWordProvider}.
+ */
+export function createPorcupine(
+  options: PorcupineWakeWordProviderOptions,
+): PorcupineWakeWordProvider {
+  return new PorcupineWakeWordProvider(options);
+}
+
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `PICOVOICE_ACCESS_KEY` secret and optional keyword configuration
+ * from the context, and returns an {@link ExtensionPack} containing a single
+ * `wake-word-provider` descriptor.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  const accessKey = context.getSecret?.('PICOVOICE_ACCESS_KEY') ?? '';
+  const opts = context.options ?? {};
+  const keywords = opts['keywords'] as string[] | undefined;
+  const sensitivities = opts['sensitivities'] as number[] | undefined;
+
+  const provider = new PorcupineWakeWordProvider({ accessKey, keywords, sensitivities });
+
+  return {
+    id: 'porcupine',
+    descriptors: [
+      {
+        id: 'porcupine',
+        kind: EXTENSION_KIND_WAKE_WORD,
+        payload: provider,
+        enableByDefault: true,
+        metadata: { providerId: 'porcupine' },
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { PorcupineWakeWordProvider } from './PorcupineWakeWordProvider.js';
+export type {
+  WakeWordDetection,
+  PorcupineWakeWordProviderOptions,
+} from './PorcupineWakeWordProvider.js';