@auxiora/conversation 1.0.0

package/dist/turn-manager.js

@@ -0,0 +1,69 @@
+import { DEFAULT_CONVERSATION_CONFIG } from './types.js';
+/** Filler words used during thinking pauses. */
+const FILLER_WORDS = ['um', 'uh', 'hmm', 'let me think', 'well'];
+/** Backchannel responses to acknowledge the user. */
+const BACKCHANNEL_RESPONSES = ['uh-huh', 'yeah', 'I see', 'right', 'got it', 'mm-hmm'];
+/**
+ * Manages turn-taking, natural pauses, backchanneling, and filler words.
+ */
+export class TurnManager {
+    config;
+    lastSpeechEnd = 0;
+    turnHistory = [];
+    constructor(config) {
+        this.config = { ...DEFAULT_CONVERSATION_CONFIG, ...config };
+    }
+    /** Record the end of a speech turn. */
+    recordTurnEnd() {
+        this.lastSpeechEnd = Date.now();
+    }
+    /** Check if enough silence has passed to end the current turn. */
+    isTurnComplete() {
+        if (this.lastSpeechEnd === 0)
+            return false;
+        return (Date.now() - this.lastSpeechEnd) >= this.config.silenceTimeout;
+    }
+    /** Get a random filler word for thinking pauses. */
+    getFiller() {
+        if (!this.config.fillersEnabled)
+            return null;
+        return FILLER_WORDS[Math.floor(Math.random() * FILLER_WORDS.length)];
+    }
+    /** Get a backchannel response to acknowledge user speech. */
+    getBackchannel() {
+        if (!this.config.backchannelEnabled)
+            return null;
+        return BACKCHANNEL_RESPONSES[Math.floor(Math.random() * BACKCHANNEL_RESPONSES.length)];
+    }
+    /** Detect if the user is attempting to interrupt. */
+    detectInterruption(speechDuration) {
+        if (!this.config.interruptionEnabled)
+            return false;
+        return speechDuration >= this.config.minSpeechDuration;
+    }
+    /** Calculate natural pause duration between sentences. */
+    calculatePause(sentenceLength) {
+        // Longer sentences get slightly longer pauses
+        const basePause = 200;
+        const lengthFactor = Math.min(sentenceLength / 100, 2);
+        return Math.round(basePause + lengthFactor * 150);
+    }
+    /** Add a turn event to history. */
+    addToHistory(event) {
+        this.turnHistory.push(event);
+        // Keep last 50 turns
+        if (this.turnHistory.length > 50) {
+            this.turnHistory = this.turnHistory.slice(-50);
+        }
+    }
+    /** Get recent turn history. */
+    getHistory(limit = 10) {
+        return this.turnHistory.slice(-limit);
+    }
+    /** Reset turn state. */
+    reset() {
+        this.lastSpeechEnd = 0;
+        this.turnHistory = [];
+    }
+}
+//# sourceMappingURL=turn-manager.js.map

package/dist/turn-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-manager.js","sourceRoot":"","sources":["../src/turn-manager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAEzD,gDAAgD;AAChD,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC;AAEjE,qDAAqD;AACrD,MAAM,qBAAqB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAqB;IAC3B,aAAa,GAAG,CAAC,CAAC;IAClB,WAAW,GAAgB,EAAE,CAAC;IAEtC,YAAY,MAAoC;QAC9C,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,2BAA2B,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9D,CAAC;IAED,uCAAuC;IACvC,aAAa;QACX,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAClC,CAAC;IAED,kEAAkE;IAClE,cAAc;QACZ,IAAI,IAAI,CAAC,aAAa,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC;IACzE,CAAC;IAED,oDAAoD;IACpD,SAAS;QACP,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc;YAAE,OAAO,IAAI,CAAC;QAC7C,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACvE,CAAC;IAED,6DAA6D;IAC7D,cAAc;QACZ,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,kBAAkB;YAAE,OAAO,IAAI,CAAC;QACjD,OAAO,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC,CAAC;IACzF,CAAC;IAED,qDAAqD;IACrD,kBAAkB,CAAC,cAAsB;QACvC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB;YAAE,OAAO,KAAK,CAAC;QACnD,OAAO,cAAc,IAAI,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC;IACzD,CAAC;IAED,0DAA0D;IAC1D,cAAc,CAAC,cAAsB;QACnC,8CAA8C;QAC9C,MAAM,SAAS,GAAG,GAAG,CAAC;QACtB,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,YAAY,GAAG,GAAG,CAAC,CAAC;IACpD,CAAC;IAED,mCAAmC;IACnC,YAAY,CAAC,KAAgB;QAC3B,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,qBAAqB;QACrB,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,EAAE,EAAE,CAAC;YACjC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,UAAU,CAAC,KAAK,GAAG,EAAE;QACnB,OAAO,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IAED,wBAAwB;IACxB,KAAK;QACH,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;IACxB,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/** States of a real-time conversation. */
+export type ConversationState = 'idle' | 'listening' | 'thinking' | 'speaking' | 'interrupted';
+/** Events emitted during a conversation turn. */
+export interface TurnEvent {
+    type: 'user_speech' | 'ai_response' | 'interruption' | 'silence' | 'backchannel' | 'filler';
+    timestamp: number;
+    /** Transcribed text (for user_speech) or response text (for ai_response). */
+    text?: string;
+    /** Audio data associated with this event. */
+    audio?: Buffer;
+    /** Duration in milliseconds. */
+    duration?: number;
+}
+/** Voice personality settings for natural conversation. */
+export interface VoicePersonality {
+    /** Speaking pace (0.5 = slow, 1.0 = normal, 1.5 = fast). */
+    pace: number;
+    /** Pitch adjustment (-1.0 to 1.0). */
+    pitch: number;
+    /** How often to use filler words (0 = never, 1 = frequently). */
+    fillerStyle: number;
+    /** Natural pause duration in milliseconds between sentences. */
+    pauseDuration: number;
+}
+export declare const DEFAULT_VOICE_PERSONALITY: VoicePersonality;
+/** Configuration for the conversation engine. */
+export interface ConversationConfig {
+    /** Voice activity detection sensitivity (0-1). */
+    vadSensitivity: number;
+    /** Maximum silence before ending a turn (ms). */
+    silenceTimeout: number;
+    /** Minimum speech duration to register as a turn (ms). */
+    minSpeechDuration: number;
+    /** Whether to enable interruption detection. */
+    interruptionEnabled: boolean;
+    /** Whether to insert filler words while thinking. */
+    fillersEnabled: boolean;
+    /** Whether to enable backchannel responses (uh-huh, yeah, etc.). */
+    backchannelEnabled: boolean;
+    /** Echo cancellation hint for the audio system. */
+    echoCancellation: boolean;
+}
+export declare const DEFAULT_CONVERSATION_CONFIG: ConversationConfig;
+/** Callback for conversation turn events. */
+export type TurnHandler = (event: TurnEvent) => void | Promise<void>;
+/** Callback for state changes. */
+export type StateHandler = (from: ConversationState, to: ConversationState) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;AAE/F,iDAAiD;AACjD,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,aAAa,GAAG,aAAa,GAAG,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,QAAQ,CAAC;IAC5F,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,yBAAyB,EAAE,gBAKvC,CAAC;AAEF,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,mBAAmB,EAAE,OAAO,CAAC;IAC7B,qDAAqD;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,oEAAoE;IACpE,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mDAAmD;IACnD,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,eAAO,MAAM,2BAA2B,EAAE,kBAQzC,CAAC;AAEF,6CAA6C;AAC7C,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAErE,kCAAkC;AAClC,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,iBAAiB,KAAK,IAAI,CAAC"}

package/dist/types.js

@@ -0,0 +1,16 @@
+export const DEFAULT_VOICE_PERSONALITY = {
+    pace: 1.0,
+    pitch: 0.0,
+    fillerStyle: 0.2,
+    pauseDuration: 300,
+};
+export const DEFAULT_CONVERSATION_CONFIG = {
+    vadSensitivity: 0.5,
+    silenceTimeout: 1500,
+    minSpeechDuration: 300,
+    interruptionEnabled: true,
+    fillersEnabled: true,
+    backchannelEnabled: true,
+    echoCancellation: true,
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2BA,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,WAAW,EAAE,GAAG;IAChB,aAAa,EAAE,GAAG;CACnB,CAAC;AAoBF,MAAM,CAAC,MAAM,2BAA2B,GAAuB;IAC7D,cAAc,EAAE,GAAG;IACnB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,GAAG;IACtB,mBAAmB,EAAE,IAAI;IACzB,cAAc,EAAE,IAAI;IACpB,kBAAkB,EAAE,IAAI;IACxB,gBAAgB,EAAE,IAAI;CACvB,CAAC"}

package/dist/voice-personality.d.ts

@@ -0,0 +1,24 @@
+import type { VoicePersonality } from './types.js';
+import type { TTSOptions } from '@auxiora/tts';
+/**
+ * Maps personality templates to TTS voice parameters.
+ */
+export declare class VoicePersonalityAdapter {
+    private personality;
+    constructor(personality?: Partial<VoicePersonality>);
+    /** Load a named personality template. */
+    static fromTemplate(name: string): VoicePersonalityAdapter;
+    /** List available personality template names. */
+    static listTemplates(): string[];
+    /** Get the current voice personality settings. */
+    getPersonality(): VoicePersonality;
+    /** Convert personality to TTS options. */
+    toTTSOptions(baseOptions?: TTSOptions): TTSOptions;
+    /** Get the natural pause duration for this personality. */
+    getPauseDuration(): number;
+    /** Whether this personality uses filler words. */
+    useFillers(): boolean;
+    /** Get filler word probability (0-1). */
+    getFillerProbability(): number;
+}
+//# sourceMappingURL=voice-personality.d.ts.map

package/dist/voice-personality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-personality.d.ts","sourceRoot":"","sources":["../src/voice-personality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAoC/C;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,WAAW,CAAmB;gBAE1B,WAAW,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAInD,yCAAyC;IACzC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB;IAQ1D,iDAAiD;IACjD,MAAM,CAAC,aAAa,IAAI,MAAM,EAAE;IAIhC,kDAAkD;IAClD,cAAc,IAAI,gBAAgB;IAIlC,0CAA0C;IAC1C,YAAY,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU;IAOlD,2DAA2D;IAC3D,gBAAgB,IAAI,MAAM;IAI1B,kDAAkD;IAClD,UAAU,IAAI,OAAO;IAIrB,yCAAyC;IACzC,oBAAoB,IAAI,MAAM;CAG/B"}

package/dist/voice-personality.js

@@ -0,0 +1,79 @@
+import { DEFAULT_VOICE_PERSONALITY } from './types.js';
+/** Named personality templates mapped to voice parameters. */
+const PERSONALITY_TEMPLATES = {
+    friendly: {
+        pace: 1.0,
+        pitch: 0.1,
+        fillerStyle: 0.3,
+        pauseDuration: 250,
+    },
+    professional: {
+        pace: 0.95,
+        pitch: 0.0,
+        fillerStyle: 0.05,
+        pauseDuration: 350,
+    },
+    enthusiastic: {
+        pace: 1.15,
+        pitch: 0.2,
+        fillerStyle: 0.4,
+        pauseDuration: 200,
+    },
+    calm: {
+        pace: 0.85,
+        pitch: -0.1,
+        fillerStyle: 0.1,
+        pauseDuration: 450,
+    },
+    concise: {
+        pace: 1.1,
+        pitch: 0.0,
+        fillerStyle: 0.0,
+        pauseDuration: 200,
+    },
+};
+/**
+ * Maps personality templates to TTS voice parameters.
+ */
+export class VoicePersonalityAdapter {
+    personality;
+    constructor(personality) {
+        this.personality = { ...DEFAULT_VOICE_PERSONALITY, ...personality };
+    }
+    /** Load a named personality template. */
+    static fromTemplate(name) {
+        const template = PERSONALITY_TEMPLATES[name];
+        if (!template) {
+            return new VoicePersonalityAdapter();
+        }
+        return new VoicePersonalityAdapter(template);
+    }
+    /** List available personality template names. */
+    static listTemplates() {
+        return Object.keys(PERSONALITY_TEMPLATES);
+    }
+    /** Get the current voice personality settings. */
+    getPersonality() {
+        return { ...this.personality };
+    }
+    /** Convert personality to TTS options. */
+    toTTSOptions(baseOptions) {
+        return {
+            ...baseOptions,
+            speed: this.personality.pace,
+        };
+    }
+    /** Get the natural pause duration for this personality. */
+    getPauseDuration() {
+        return this.personality.pauseDuration;
+    }
+    /** Whether this personality uses filler words. */
+    useFillers() {
+        return this.personality.fillerStyle > 0;
+    }
+    /** Get filler word probability (0-1). */
+    getFillerProbability() {
+        return this.personality.fillerStyle;
+    }
+}
+//# sourceMappingURL=voice-personality.js.map

package/dist/voice-personality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-personality.js","sourceRoot":"","sources":["../src/voice-personality.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAGvD,8DAA8D;AAC9D,MAAM,qBAAqB,GAAqC;IAC9D,QAAQ,EAAE;QACR,IAAI,EAAE,GAAG;QACT,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,GAAG;QAChB,aAAa,EAAE,GAAG;KACnB;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,GAAG;KACnB;IACD,YAAY,EAAE;QACZ,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,GAAG;QAChB,aAAa,EAAE,GAAG;KACnB;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,CAAC,GAAG;QACX,WAAW,EAAE,GAAG;QAChB,aAAa,EAAE,GAAG;KACnB;IACD,OAAO,EAAE;QACP,IAAI,EAAE,GAAG;QACT,KAAK,EAAE,GAAG;QACV,WAAW,EAAE,GAAG;QAChB,aAAa,EAAE,GAAG;KACnB;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAC1B,WAAW,CAAmB;IAEtC,YAAY,WAAuC;QACjD,IAAI,CAAC,WAAW,GAAG,EAAE,GAAG,yBAAyB,EAAE,GAAG,WAAW,EAAE,CAAC;IACtE,CAAC;IAED,yCAAyC;IACzC,MAAM,CAAC,YAAY,CAAC,IAAY;QAC9B,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,IAAI,uBAAuB,EAAE,CAAC;QACvC,CAAC;QACD,OAAO,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,iDAAiD;IACjD,MAAM,CAAC,aAAa;QAClB,OAAO,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC5C,CAAC;IAED,kDAAkD;IAClD,cAAc;QACZ,OAAO,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;IAED,0CAA0C;IAC1C,YAAY,CAAC,WAAwB;QACnC,OAAO;YACL,GAAG,WAAW;YACd,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI;SAC7B,CAAC;IACJ,CAAC;IAED,2DAA2D;IAC3D,gBAAgB;QACd,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC;IACxC,CAAC;IAED,kDAAkD;IAClD,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,yCAAyC;IACzC,oBAAoB;QAClB,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC;IACtC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@auxiora/conversation",
+  "version": "1.0.0",
+  "description": "Real-time voice conversation engine with state machine, turn-taking, and voice personality",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@auxiora/personality": "1.0.0",
+    "@auxiora/stt": "1.0.0",
+    "@auxiora/tts": "1.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/engine.ts

@@ -0,0 +1,156 @@
+import type {
+  ConversationState,
+  ConversationConfig,
+  TurnEvent,
+  TurnHandler,
+  StateHandler,
+} from './types.js';
+import { DEFAULT_CONVERSATION_CONFIG } from './types.js';
+
+/** Valid state transitions. */
+const VALID_TRANSITIONS: Record<ConversationState, ConversationState[]> = {
+  idle: ['listening'],
+  listening: ['thinking', 'idle'],
+  thinking: ['speaking', 'idle'],
+  speaking: ['idle', 'interrupted'],
+  interrupted: ['listening', 'idle'],
+};
+
+/**
+ * Conversation engine — manages the state machine for real-time voice conversations.
+ * State flow: idle -> listening -> thinking -> speaking -> idle
+ * Interruption: speaking -> interrupted -> listening
+ */
+export class ConversationEngine {
+  private state: ConversationState = 'idle';
+  private config: ConversationConfig;
+  private turnHandlers: TurnHandler[] = [];
+  private stateHandlers: StateHandler[] = [];
+  private turnCount = 0;
+
+  constructor(config?: Partial<ConversationConfig>) {
+    this.config = { ...DEFAULT_CONVERSATION_CONFIG, ...config };
+  }
+
+  /** Start a conversation session (idle -> listening). */
+  start(): void {
+    this.transition('listening');
+  }
+
+  /** Stop the conversation (any state -> idle). */
+  stop(): void {
+    this.state = 'idle';
+    this.turnCount = 0;
+    for (const handler of this.stateHandlers) {
+      handler(this.state, 'idle');
+    }
+  }
+
+  /** Get current state. */
+  getState(): ConversationState {
+    return this.state;
+  }
+
+  /** Get number of turns completed. */
+  getTurnCount(): number {
+    return this.turnCount;
+  }
+
+  /** Register a turn event handler. */
+  onTurn(handler: TurnHandler): void {
+    this.turnHandlers.push(handler);
+  }
+
+  /** Register a state change handler. */
+  onStateChange(handler: StateHandler): void {
+    this.stateHandlers.push(handler);
+  }
+
+  /** Transition to a new state. */
+  transition(to: ConversationState): void {
+    const from = this.state;
+    const allowed = VALID_TRANSITIONS[from];
+    if (!allowed.includes(to)) {
+      throw new Error(`Invalid transition: ${from} -> ${to}`);
+    }
+    this.state = to;
+    for (const handler of this.stateHandlers) {
+      handler(from, to);
+    }
+  }
+
+  /** Process user speech input. */
+  async handleUserSpeech(text: string, audio?: Buffer): Promise<void> {
+    if (this.state !== 'listening') {
+      throw new Error(`Cannot process speech in state: ${this.state}`);
+    }
+
+    const event: TurnEvent = {
+      type: 'user_speech',
+      timestamp: Date.now(),
+      text,
+      audio,
+    };
+
+    await this.emitTurn(event);
+    this.transition('thinking');
+    this.turnCount++;
+  }
+
+  /** Process AI response. */
+  async handleAIResponse(text: string, audio?: Buffer): Promise<void> {
+    if (this.state !== 'thinking') {
+      throw new Error(`Cannot send response in state: ${this.state}`);
+    }
+
+    this.transition('speaking');
+
+    const event: TurnEvent = {
+      type: 'ai_response',
+      timestamp: Date.now(),
+      text,
+      audio,
+    };
+
+    await this.emitTurn(event);
+  }
+
+  /** Signal that speaking is complete, return to listening. */
+  finishSpeaking(): void {
+    if (this.state !== 'speaking') {
+      throw new Error(`Cannot finish speaking in state: ${this.state}`);
+    }
+    this.transition('idle');
+    this.transition('listening');
+  }
+
+  /** Handle an interruption (user starts talking while AI is speaking). */
+  async handleInterruption(): Promise<void> {
+    if (this.state !== 'speaking') {
+      throw new Error(`Cannot interrupt in state: ${this.state}`);
+    }
+
+    if (!this.config.interruptionEnabled) return;
+
+    this.transition('interrupted');
+
+    const event: TurnEvent = {
+      type: 'interruption',
+      timestamp: Date.now(),
+    };
+    await this.emitTurn(event);
+
+    this.transition('listening');
+  }
+
+  /** Get current config. */
+  getConfig(): ConversationConfig {
+    return { ...this.config };
+  }
+
+  private async emitTurn(event: TurnEvent): Promise<void> {
+    for (const handler of this.turnHandlers) {
+      await handler(event);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export type {
+  ConversationState,
+  ConversationConfig,
+  TurnEvent,
+  VoicePersonality,
+  TurnHandler,
+  StateHandler,
+} from './types.js';
+export {
+  DEFAULT_CONVERSATION_CONFIG,
+  DEFAULT_VOICE_PERSONALITY,
+} from './types.js';
+export { ConversationEngine } from './engine.js';
+export { TurnManager } from './turn-manager.js';
+export { VoicePersonalityAdapter } from './voice-personality.js';
+export {
+  AudioStreamManager,
+  type AudioStreamEvent,
+  type StreamDirection,
+} from './stream.js';

package/src/stream.ts

@@ -0,0 +1,133 @@
+import type { ConversationConfig } from './types.js';
+import { DEFAULT_CONVERSATION_CONFIG } from './types.js';
+
+/** Audio stream direction. */
+export type StreamDirection = 'inbound' | 'outbound';
+
+/** Audio stream event. */
+export interface AudioStreamEvent {
+  direction: StreamDirection;
+  timestamp: number;
+  /** Audio data chunk. */
+  data: Buffer;
+  /** Whether voice activity was detected in this chunk. */
+  voiceDetected?: boolean;
+}
+
+/**
+ * Manages bidirectional audio streaming with VAD and echo cancellation hints.
+ */
+export class AudioStreamManager {
+  private config: ConversationConfig;
+  private inboundBuffer: Buffer[] = [];
+  private outboundBuffer: Buffer[] = [];
+  private active = false;
+  private vadState = false;
+  private listeners: Array<(event: AudioStreamEvent) => void> = [];
+
+  constructor(config?: Partial<ConversationConfig>) {
+    this.config = { ...DEFAULT_CONVERSATION_CONFIG, ...config };
+  }
+
+  /** Start the audio stream. */
+  start(): void {
+    this.active = true;
+    this.inboundBuffer = [];
+    this.outboundBuffer = [];
+    this.vadState = false;
+  }
+
+  /** Stop the audio stream. */
+  stop(): void {
+    this.active = false;
+    this.inboundBuffer = [];
+    this.outboundBuffer = [];
+  }
+
+  /** Whether the stream is active. */
+  isActive(): boolean {
+    return this.active;
+  }
+
+  /** Push inbound audio (from microphone). */
+  pushInbound(data: Buffer): void {
+    if (!this.active) return;
+    this.inboundBuffer.push(data);
+
+    const voiceDetected = this.detectVoiceActivity(data);
+    this.vadState = voiceDetected;
+
+    this.emit({
+      direction: 'inbound',
+      timestamp: Date.now(),
+      data,
+      voiceDetected,
+    });
+  }
+
+  /** Push outbound audio (to speaker). */
+  pushOutbound(data: Buffer): void {
+    if (!this.active) return;
+    this.outboundBuffer.push(data);
+
+    this.emit({
+      direction: 'outbound',
+      timestamp: Date.now(),
+      data,
+    });
+  }
+
+  /** Get accumulated inbound audio and clear the buffer. */
+  flushInbound(): Buffer {
+    const combined = Buffer.concat(this.inboundBuffer);
+    this.inboundBuffer = [];
+    return combined;
+  }
+
+  /** Get accumulated outbound audio and clear the buffer. */
+  flushOutbound(): Buffer {
+    const combined = Buffer.concat(this.outboundBuffer);
+    this.outboundBuffer = [];
+    return combined;
+  }
+
+  /** Whether voice activity is currently detected. */
+  isVoiceActive(): boolean {
+    return this.vadState;
+  }
+
+  /** Whether echo cancellation is enabled. */
+  isEchoCancellationEnabled(): boolean {
+    return this.config.echoCancellation;
+  }
+
+  /** Register an audio stream event listener. */
+  onAudio(listener: (event: AudioStreamEvent) => void): void {
+    this.listeners.push(listener);
+  }
+
+  /**
+   * Simple energy-based voice activity detection.
+   * Compares average sample amplitude against the sensitivity threshold.
+   */
+  private detectVoiceActivity(data: Buffer): boolean {
+    if (data.length < 2) return false;
+
+    let energy = 0;
+    const samples = data.length / 2; // 16-bit samples
+    for (let i = 0; i < data.length - 1; i += 2) {
+      const sample = data.readInt16LE(i);
+      energy += Math.abs(sample);
+    }
+    const avgEnergy = energy / samples;
+    // Normalize to 0-1 range (Int16 max = 32767)
+    const normalized = avgEnergy / 32767;
+    return normalized > this.config.vadSensitivity;
+  }
+
+  private emit(event: AudioStreamEvent): void {
+    for (const listener of this.listeners) {
+      listener(event);
+    }
+  }
+}

package/src/turn-manager.ts

@@ -0,0 +1,78 @@
+import type { ConversationConfig, TurnEvent } from './types.js';
+import { DEFAULT_CONVERSATION_CONFIG } from './types.js';
+
+/** Filler words used during thinking pauses. */
+const FILLER_WORDS = ['um', 'uh', 'hmm', 'let me think', 'well'];
+
+/** Backchannel responses to acknowledge the user. */
+const BACKCHANNEL_RESPONSES = ['uh-huh', 'yeah', 'I see', 'right', 'got it', 'mm-hmm'];
+
+/**
+ * Manages turn-taking, natural pauses, backchanneling, and filler words.
+ */
+export class TurnManager {
+  private config: ConversationConfig;
+  private lastSpeechEnd = 0;
+  private turnHistory: TurnEvent[] = [];
+
+  constructor(config?: Partial<ConversationConfig>) {
+    this.config = { ...DEFAULT_CONVERSATION_CONFIG, ...config };
+  }
+
+  /** Record the end of a speech turn. */
+  recordTurnEnd(): void {
+    this.lastSpeechEnd = Date.now();
+  }
+
+  /** Check if enough silence has passed to end the current turn. */
+  isTurnComplete(): boolean {
+    if (this.lastSpeechEnd === 0) return false;
+    return (Date.now() - this.lastSpeechEnd) >= this.config.silenceTimeout;
+  }
+
+  /** Get a random filler word for thinking pauses. */
+  getFiller(): string | null {
+    if (!this.config.fillersEnabled) return null;
+    return FILLER_WORDS[Math.floor(Math.random() * FILLER_WORDS.length)];
+  }
+
+  /** Get a backchannel response to acknowledge user speech. */
+  getBackchannel(): string | null {
+    if (!this.config.backchannelEnabled) return null;
+    return BACKCHANNEL_RESPONSES[Math.floor(Math.random() * BACKCHANNEL_RESPONSES.length)];
+  }
+
+  /** Detect if the user is attempting to interrupt. */
+  detectInterruption(speechDuration: number): boolean {
+    if (!this.config.interruptionEnabled) return false;
+    return speechDuration >= this.config.minSpeechDuration;
+  }
+
+  /** Calculate natural pause duration between sentences. */
+  calculatePause(sentenceLength: number): number {
+    // Longer sentences get slightly longer pauses
+    const basePause = 200;
+    const lengthFactor = Math.min(sentenceLength / 100, 2);
+    return Math.round(basePause + lengthFactor * 150);
+  }
+
+  /** Add a turn event to history. */
+  addToHistory(event: TurnEvent): void {
+    this.turnHistory.push(event);
+    // Keep last 50 turns
+    if (this.turnHistory.length > 50) {
+      this.turnHistory = this.turnHistory.slice(-50);
+    }
+  }
+
+  /** Get recent turn history. */
+  getHistory(limit = 10): TurnEvent[] {
+    return this.turnHistory.slice(-limit);
+  }
+
+  /** Reset turn state. */
+  reset(): void {
+    this.lastSpeechEnd = 0;
+    this.turnHistory = [];
+  }
+}