Add the VoiceAgent core: facade, funnel, turn detection, clause chunking

Phase 3 of the AWS.Speech.MEAI stack. Composes the Polly TTS and Transcribe STT
clients from PR 2 and any MEAI IChatClient into a full-duplex voice loop that
emits one ordered stream of VoiceAgentUpdate values.

Public API (all net8-only, all [Experimental("MEAI001")]):
- VoiceAgent (IAsyncDisposable): provider-neutral ctor + Create(...) factory
  that constructs Amazon Transcribe / Bedrock / Polly clients from the default
  chains, honoring VoiceAgentOptions.Credentials and Region. Owned AWS clients
  are disposed on DisposeAsync. GetService exposes the underlying MEAI clients.
- VoiceAgentOptions: ModelId, Voice, Instructions, Language, sample rates,
  Tools, Region, Credentials, Backend (Pipeline default; NovaSonic reserved
  for PR 5), plus pre-built STT/chat/TTS overrides.
- VoiceAgentUpdate readonly record struct and VoiceAgentUpdateKind
  (UserTranscriptPartial/Final, TurnStarted, AssistantText, AssistantAudio,
  TurnComplete, Cancelled).
- VoiceAgentBackend (Pipeline, NovaSonic). Create throws NotSupportedException
  for NovaSonic; wired in PR 5.

Internal implementation:
- VoiceAgentPipeline drives the loop. A single-reader output channel funnels
  updates from two producers (an STT consumer and a reasoning-plus-TTS worker)
  so the caller sees one ordered stream. A separate user-turn channel enqueues
  each finalized user utterance for the reasoning worker to drain.
- ClauseChunker returns the first punctuation boundary at or past a minimum
  clause length so completed clauses can be spoken while the model is still
  writing later ones. This keeps time-to-first-audio low.
- History is maintained in-process; Instructions seeds a system message.
- On teardown or cancellation, the linked CTS cancels both producers, the
  writer closes, and the first non-cancellation failure is rethrown via
  ExceptionDispatchInfo.

Not in this PR (stack roadmap):
- Barge-in, the Nova Sonic backend, AsIRealtimeClient(), and AddVoiceAgent DI
  (PR 5).
- Live device sample and integration tests (PRs 6 and 7).

Testing: 5 clause-chunker tests + 6 pipeline tests via inline STT/chat/TTS
stubs (single-turn ordering, clause chunking, whitespace-final gate,
system-message seeding, null-arg + disposal + GetService). All Speech tests
pass on net8.0 (24) and net472 (7, unchanged). All 243 net8.0 + 173 net472
Bedrock/Nova tests still pass unchanged.

Author: GarrettBeatty

src/AWS.Speech.MEAI/ClauseChunker.cs

@@ -0,0 +1,45 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#if NET8_0_OR_GREATER
+using System.Text;
+
+namespace AWS.Speech.MEAI;
+
+/// <summary>
+/// Finds clause boundaries in streaming assistant text so the pipeline can send completed clauses to
+/// text-to-speech while the model is still writing later ones. This keeps time-to-first-audio low.
+/// </summary>
+internal static class ClauseChunker
+{
+    /// <summary>Minimum clause length in characters; guards against flushing single-word fragments.</summary>
+    internal const int MinClauseLength = 12;
+
+    /// <summary>
+    /// Returns the length of the prefix of <paramref name="buffer"/> that should be flushed as a clause,
+    /// or 0 if no boundary meets the minimum length yet.
+    /// </summary>
+    /// <remarks>
+    /// Walks from <see cref="MinClauseLength"/> - 1 onwards so short fragments never trigger a flush.
+    /// Returns at the first boundary that qualifies so first-audio latency stays low.
+    /// </remarks>
+    public static int NextClauseBoundary(StringBuilder buffer)
+    {
+        for (int i = MinClauseLength - 1; i < buffer.Length; i++)
+        {
+            switch (buffer[i])
+            {
+                case '.':
+                case '?':
+                case '!':
+                case ',':
+                case ';':
+                case ':':
+                case '\n':
+                    return i + 1;
+            }
+        }
+        return 0;
+    }
+}
+#endif

src/AWS.Speech.MEAI/VoiceAgent.cs

@@ -0,0 +1,192 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#if NET8_0_OR_GREATER
+using Amazon;
+using Amazon.BedrockRuntime;
+using Amazon.Polly;
+using Amazon.Runtime;
+using Amazon.TranscribeStreaming;
+using Microsoft.Extensions.AI;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace AWS.Speech.MEAI;
+
+/// <summary>
+/// Composes an <see cref="ISpeechToTextClient"/>, an <see cref="IChatClient"/>, and an
+/// <see cref="ITextToSpeechClient"/> into a full-duplex voice loop that emits one ordered stream of
+/// <see cref="VoiceAgentUpdate"/>s.
+/// </summary>
+/// <remarks>
+/// The default backend is <see cref="VoiceAgentBackend.Pipeline"/>: Amazon Transcribe streaming for
+/// STT, Amazon Bedrock via <c>AWS.Bedrock.MEAI</c> for reasoning, and Amazon Polly for TTS. Call
+/// <see cref="Create"/> for the one-line default-chain factory, or use the constructor to compose any
+/// MEAI clients you already have. Barge-in, the Nova Sonic backend swap, the <c>AsIRealtimeClient()</c>
+/// adapter, and DI registration are wired in a later phase.
+/// </remarks>
+[Experimental("MEAI001")]
+public sealed class VoiceAgent : IAsyncDisposable
+{
+    private readonly ISpeechToTextClient _stt;
+    private readonly IChatClient _chat;
+    private readonly ITextToSpeechClient _tts;
+    private readonly VoiceAgentOptions _options;
+    private readonly List<IDisposable> _ownedResources;
+    private int _disposed;
+
+    /// <summary>Initializes a provider-neutral <see cref="VoiceAgent"/> around any MEAI clients.</summary>
+    /// <exception cref="ArgumentNullException">A client is <see langword="null"/>.</exception>
+    public VoiceAgent(ISpeechToTextClient stt, IChatClient chat, ITextToSpeechClient tts, VoiceAgentOptions? options = null)
+        : this(stt, chat, tts, options ?? new VoiceAgentOptions(), ownedResources: null)
+    {
+    }
+
+    private VoiceAgent(ISpeechToTextClient stt, IChatClient chat, ITextToSpeechClient tts,
+        VoiceAgentOptions options, List<IDisposable>? ownedResources)
+    {
+        _stt = stt ?? throw new ArgumentNullException(nameof(stt));
+        _chat = chat ?? throw new ArgumentNullException(nameof(chat));
+        _tts = tts ?? throw new ArgumentNullException(nameof(tts));
+        _options = options;
+        _ownedResources = ownedResources ?? new List<IDisposable>();
+    }
+
+    /// <summary>Creates a <see cref="VoiceAgent"/> with the default AWS credential and region chains.</summary>
+    /// <remarks>
+    /// Constructs an Amazon Transcribe streaming client, an Amazon Bedrock runtime client (adapted via
+    /// <c>AmazonBedrockRuntimeExtensions.AsIChatClient</c>), and an Amazon Polly client, honoring
+    /// <see cref="VoiceAgentOptions.Credentials"/> and <see cref="VoiceAgentOptions.Region"/> when set.
+    /// A pre-built client on the options object wins over the default AWS client for that leg. The
+    /// returned agent owns any clients it constructed and disposes them on <see cref="DisposeAsync"/>.
+    /// </remarks>
+    /// <exception cref="NotSupportedException">The requested backend is not yet available in this preview.</exception>
+    public static VoiceAgent Create(Action<VoiceAgentOptions>? configure = null)
+    {
+        var options = new VoiceAgentOptions();
+        configure?.Invoke(options);
+
+        if (options.Backend != VoiceAgentBackend.Pipeline)
+        {
+            throw new NotSupportedException(
+                $"The {options.Backend} backend is not available yet in this preview. Use VoiceAgentBackend.Pipeline.");
+        }
+
+        var owned = new List<IDisposable>();
+
+        var stt = options.SpeechToTextClient;
+        if (stt is null)
+        {
+            var transcribe = CreateTranscribeClient(options.Credentials, options.Region);
+            owned.Add(transcribe);
+            stt = transcribe.AsISpeechToTextClient(options.Language, options.InputSampleRateHertz);
+        }
+
+        var chat = options.ChatClient;
+        if (chat is null)
+        {
+            var bedrock = CreateBedrockClient(options.Credentials, options.Region);
+            owned.Add(bedrock);
+            chat = bedrock.AsIChatClient(options.ModelId);
+        }
+
+        var tts = options.TextToSpeechClient;
+        if (tts is null)
+        {
+            var polly = CreatePollyClient(options.Credentials, options.Region);
+            owned.Add(polly);
+            tts = polly.AsITextToSpeechClient(options.Voice, Engine.Neural, options.OutputSampleRateHertz);
+        }
+
+        return new VoiceAgent(stt, chat, tts, options, owned);
+    }
+
+    /// <summary>Runs the voice loop over the caller's microphone PCM stream.</summary>
+    /// <param name="microphonePcm">
+    /// Input audio at <see cref="VoiceAgentOptions.InputSampleRateHertz"/>, 16-bit signed
+    /// little-endian mono PCM. The agent never disposes this stream.
+    /// </param>
+    /// <param name="cancellationToken">Stops the loop; the returned enumerable then completes.</param>
+    /// <returns>One ordered stream of <see cref="VoiceAgentUpdate"/>s.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="microphonePcm"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ObjectDisposedException">The agent has been disposed.</exception>
+    public IAsyncEnumerable<VoiceAgentUpdate> RunAsync(Stream microphonePcm, CancellationToken cancellationToken = default)
+    {
+        if (microphonePcm is null) throw new ArgumentNullException(nameof(microphonePcm));
+        ThrowIfDisposed();
+
+        return VoiceAgentPipeline.RunAsync(_stt, _chat, _tts, _options, microphonePcm, cancellationToken);
+    }
+
+    /// <summary>Returns the underlying MEAI client for the requested service type, or <see langword="null"/>.</summary>
+    public object? GetService(System.Type serviceType, object? serviceKey = null)
+    {
+        if (serviceType is null) throw new ArgumentNullException(nameof(serviceType));
+        if (serviceKey is not null) return null;
+
+        if (serviceType == typeof(ISpeechToTextClient)) return _stt;
+        if (serviceType == typeof(IChatClient)) return _chat;
+        if (serviceType == typeof(ITextToSpeechClient)) return _tts;
+        return serviceType.IsInstanceOfType(this) ? this : null;
+    }
+
+    /// <inheritdoc/>
+    public ValueTask DisposeAsync()
+    {
+        if (Interlocked.Exchange(ref _disposed, 1) != 0) return default;
+
+        Exception? first = null;
+        foreach (var resource in _ownedResources)
+        {
+            try { resource.Dispose(); }
+            catch (Exception ex) { first ??= ex; }
+        }
+        _ownedResources.Clear();
+
+        if (first is not null)
+        {
+            System.Runtime.ExceptionServices.ExceptionDispatchInfo.Capture(first).Throw();
+        }
+        return default;
+    }
+
+    private void ThrowIfDisposed()
+    {
+        if (Volatile.Read(ref _disposed) != 0)
+        {
+            throw new ObjectDisposedException(nameof(VoiceAgent));
+        }
+    }
+
+    private static AmazonTranscribeStreamingClient CreateTranscribeClient(AWSCredentials? credentials, RegionEndpoint? region) =>
+        (credentials, region) switch
+        {
+            (null, null) => new AmazonTranscribeStreamingClient(),
+            (null, _) => new AmazonTranscribeStreamingClient(region),
+            (_, null) => new AmazonTranscribeStreamingClient(credentials),
+            _ => new AmazonTranscribeStreamingClient(credentials, region),
+        };
+
+    private static AmazonBedrockRuntimeClient CreateBedrockClient(AWSCredentials? credentials, RegionEndpoint? region) =>
+        (credentials, region) switch
+        {
+            (null, null) => new AmazonBedrockRuntimeClient(),
+            (null, _) => new AmazonBedrockRuntimeClient(region),
+            (_, null) => new AmazonBedrockRuntimeClient(credentials),
+            _ => new AmazonBedrockRuntimeClient(credentials, region),
+        };
+
+    private static AmazonPollyClient CreatePollyClient(AWSCredentials? credentials, RegionEndpoint? region) =>
+        (credentials, region) switch
+        {
+            (null, null) => new AmazonPollyClient(),
+            (null, _) => new AmazonPollyClient(region),
+            (_, null) => new AmazonPollyClient(credentials),
+            _ => new AmazonPollyClient(credentials, region),
+        };
+}
+#endif

src/AWS.Speech.MEAI/VoiceAgentBackend.cs

@@ -0,0 +1,19 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#if NET8_0_OR_GREATER
+using System.Diagnostics.CodeAnalysis;
+
+namespace AWS.Speech.MEAI;
+
+/// <summary>Selects which backend drives a <see cref="VoiceAgent"/>.</summary>
+[Experimental("MEAI001")]
+public enum VoiceAgentBackend
+{
+    /// <summary>The STT + <c>IChatClient</c> + TTS composition (default).</summary>
+    Pipeline,
+
+    /// <summary>Amazon Bedrock Nova Sonic single-model speech-to-speech (wired in a later phase).</summary>
+    NovaSonic,
+}
+#endif

src/AWS.Speech.MEAI/VoiceAgentOptions.cs

@@ -0,0 +1,63 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+#if NET8_0_OR_GREATER
+using Amazon;
+using Amazon.Polly;
+using Amazon.Runtime;
+using Microsoft.Extensions.AI;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace AWS.Speech.MEAI;
+
+/// <summary>Configuration for a <see cref="VoiceAgent"/>.</summary>
+[Experimental("MEAI001")]
+public sealed class VoiceAgentOptions
+{
+    /// <summary>The Amazon Bedrock model ID for the reasoning step (for example, an Anthropic Claude model).</summary>
+    public string? ModelId { get; set; }
+
+    /// <summary>The Amazon Polly voice to synthesize with. Defaults to <see cref="VoiceId.Matthew"/>.</summary>
+    public VoiceId Voice { get; set; } = VoiceId.Matthew;
+
+    /// <summary>The system prompt, applied at the start of the conversation history.</summary>
+    public string? Instructions { get; set; }
+
+    /// <summary>The Amazon Transcribe language code. Defaults to <c>en-US</c>.</summary>
+    public string Language { get; set; } = "en-US";
+
+    /// <summary>Input PCM sample rate in hertz. Defaults to 16000.</summary>
+    public int InputSampleRateHertz { get; set; } = 16000;
+
+    /// <summary>Output PCM sample rate in hertz. Defaults to 16000; Amazon Polly PCM supports only 8000 or 16000.</summary>
+    public int OutputSampleRateHertz { get; set; } = 16000;
+
+    /// <summary>Enables barge-in (wired in a later phase).</summary>
+    public bool EnableBargeIn { get; set; } = true;
+
+    /// <summary>End-of-utterance debounce (wired with the barge-in tuning pass in a later phase).</summary>
+    public int EndOfUtteranceSilenceMs { get; set; } = 700;
+
+    /// <summary>Tools passed through to the reasoning <c>IChatClient</c> via <see cref="ChatOptions.Tools"/>.</summary>
+    public IList<AITool>? Tools { get; set; }
+
+    /// <summary>The AWS region for the constructed AWS clients. <see langword="null"/> uses the default region chain.</summary>
+    public RegionEndpoint? Region { get; set; }
+
+    /// <summary>The AWS credentials for the constructed AWS clients. <see langword="null"/> uses the default credential chain.</summary>
+    public AWSCredentials? Credentials { get; set; }
+
+    /// <summary>Which backend drives the agent. Defaults to <see cref="VoiceAgentBackend.Pipeline"/>.</summary>
+    public VoiceAgentBackend Backend { get; set; } = VoiceAgentBackend.Pipeline;
+
+    /// <summary>Pre-built speech-to-text client. When set, wins over the default AWS client chain.</summary>
+    public ISpeechToTextClient? SpeechToTextClient { get; set; }
+
+    /// <summary>Pre-built chat client. When set, wins over the default AWS client chain.</summary>
+    public IChatClient? ChatClient { get; set; }
+
+    /// <summary>Pre-built text-to-speech client. When set, wins over the default AWS client chain.</summary>
+    public ITextToSpeechClient? TextToSpeechClient { get; set; }
+}
+#endif