Fix/12293 voice type (#12329)

## Description

Fixed type error when passing MastraVoice implementations (like
OpenAIVoice) directly to Agent's voice config. The `AgentConfig.voice`
property was typed as `CompositeVoice` instead of `MastraVoice`, causing
TypeScript errors when users tried to pass voice providers directly.

Changed `voice?: CompositeVoice` to `voice?: MastraVoice` in both
`types.ts` and `agent.ts`.

## Related Issue(s)

Fixes #12293

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

* **New Features**
* Agent voice configuration has been enhanced to accept any voice
implementation directly. Previously, voices required wrapping; now you
can pass implementations like OpenAIVoice without additional abstraction
layers.

* **Tests**
* Added comprehensive type compatibility tests to validate voice
implementation usage across different voice types.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: graysonhicks

.changeset/perky-trains-grab.md

@@ -0,0 +1,23 @@
+---
+'@mastra/core': patch
+---
+
+Fixed type error when passing MastraVoice implementations (like OpenAIVoice) directly to Agent's voice config. Previously, the voice property only accepted CompositeVoice, requiring users to wrap their voice provider. Now you can pass any MastraVoice implementation directly.
+
+**Before (required wrapper):**
+
+```typescript
+const agent = new Agent({
+  voice: new CompositeVoice({ output: new OpenAIVoice() }),
+});
+```
+
+**After (direct usage):**
+
+```typescript
+const agent = new Agent({
+  voice: new OpenAIVoice(),
+});
+```
+
+Fixes #12293

packages/core/src/agent/__tests__/voice.test.ts

@@ -1,9 +1,10 @@
 import { PassThrough } from 'node:stream';
 import { openai } from '@ai-sdk/openai-v5';
-import { beforeEach, describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, expectTypeOf } from 'vitest';
 import { CompositeVoice } from '../../voice/composite-voice';
 import { MastraVoice } from '../../voice/voice';
 import { Agent } from '../agent';
+import type { AgentConfig } from '../types';
 
 describe('voice capabilities', () => {
   class MockVoice extends MastraVoice {
@@ -122,4 +123,60 @@ describe('voice capabilities', () => {
       await expect(agentWithoutVoice.voice.listen(new PassThrough())).rejects.toThrow('No voice provider configured');
     });
   });
+
+  /**
+   * Type compatibility tests for GitHub Issue #12293
+   * https://github.com/mastra-ai/mastra/issues/12293
+   *
+   * Verifies that MastraVoice implementations (like OpenAIVoice) can be
+   * passed directly to Agent.voice without wrapping in CompositeVoice.
+   */
+  describe('type compatibility (issue #12293)', () => {
+    it('AgentConfig.voice should accept MastraVoice', () => {
+      type VoiceConfigType = NonNullable<AgentConfig['voice']>;
+      expectTypeOf<MastraVoice>().toMatchTypeOf<VoiceConfigType>();
+    });
+
+    it('AgentConfig.voice should accept MastraVoice subclasses', () => {
+      type VoiceConfigType = NonNullable<AgentConfig['voice']>;
+      expectTypeOf<MockVoice>().toMatchTypeOf<VoiceConfigType>();
+    });
+
+    it('AgentConfig.voice should accept CompositeVoice', () => {
+      type VoiceConfigType = NonNullable<AgentConfig['voice']>;
+      expectTypeOf<CompositeVoice>().toMatchTypeOf<VoiceConfigType>();
+    });
+
+    it('should accept MastraVoice directly without CompositeVoice wrapper', () => {
+      const mockVoice = new MockVoice({ speaker: 'mock-voice' });
+
+      const agent = new Agent({
+        id: 'direct-voice-agent',
+        name: 'Direct Voice Agent',
+        instructions: 'You are a voice assistant.',
+        model: openai('gpt-4o-mini'),
+        voice: mockVoice,
+      });
+
+      expect(agent.voice).toBeDefined();
+    });
+
+    it('voice methods should work when MastraVoice passed directly', async () => {
+      const mockVoice = new MockVoice({ speaker: 'mock-voice' });
+
+      const agent = new Agent({
+        id: 'direct-voice-agent',
+        name: 'Direct Voice Agent',
+        instructions: 'You are a voice assistant.',
+        model: openai('gpt-4o-mini'),
+        voice: mockVoice,
+      });
+
+      const speakers = await agent.voice.getSpeakers();
+      expect(speakers).toEqual([{ voiceId: 'mock-voice' }]);
+
+      const audioStream = await agent.voice.speak('Hello');
+      expect(audioStream).toBeDefined();
+    });
+  });
 });

packages/core/src/agent/agent.ts

@@ -45,7 +45,7 @@ import type { CoreTool } from '../tools/types';
 import type { DynamicArgument } from '../types';
 import { makeCoreTool, createMastraProxy, ensureToolProperties, isZodType } from '../utils';
 import type { ToolOptions } from '../utils';
-import type { CompositeVoice } from '../voice';
+import type { MastraVoice } from '../voice';
 import { DefaultVoice } from '../voice';
 import { createWorkflow, createStep, isProcessor } from '../workflows';
 import type { OutputWriter, Step, Workflow, WorkflowResult } from '../workflows';
@@ -139,7 +139,7 @@ export class Agent<
   #tools: DynamicArgument<TTools>;
   #scorers: DynamicArgument<MastraScorers>;
   #agents: DynamicArgument<Record<string, Agent>>;
-  #voice: CompositeVoice;
+  #voice: MastraVoice;
   #inputProcessors?: DynamicArgument<InputProcessorOrWorkflow[]>;
   #outputProcessors?: DynamicArgument<OutputProcessorOrWorkflow[]>;
   #maxProcessorRetries?: number;

packages/core/src/agent/types.ts

@@ -32,7 +32,7 @@ import type { OutputSchema } from '../stream';
 import type { ModelManagerModelConfig } from '../stream/types';
 import type { ToolAction, VercelTool, VercelToolV5 } from '../tools';
 import type { DynamicArgument } from '../types';
-import type { CompositeVoice } from '../voice';
+import type { MastraVoice } from '../voice';
 import type { Workflow } from '../workflows';
 import type { Agent } from './agent';
 import type { AgentExecutionOptions, NetworkOptions } from './agent.types';
@@ -222,7 +222,7 @@ export interface AgentConfig<
   /**
    * Voice settings for speech input and output.
    */
-  voice?: CompositeVoice;
+  voice?: MastraVoice;
   /**
    * Input processors that can modify or validate messages before they are processed by the agent.
    * These can be individual processors (implementing `processInput` or `processInputStep`) or