Add C++ SDK for live audio transcription streaming

Port C# LiveAudioTranscriptionSession (PR #485) to idiomatic C++17.

New files:
- sdk/cpp/include/foundry_local/  Public headers
- sdk/cpp/src/  Implementation
- sdk/cpp/tests/  Unit tests (57) and E2E tests (3)
- sdk/cpp/CMakeLists.txt  Build system with FetchContent deps

API surface:
- LiveAudioTranscriptionSession: start/append/try_get_next/stop
- AudioClient: factory for transcription sessions
- CoreInterop: dynamic FFI loading for native core
- ThreadSafeQueue: bounded producer-consumer queue

Design highlights:
- Full API parity with C# implementation
- Thread-safe append from any thread (audio callbacks)
- Bounded backpressure on push queue
- Settings frozen at start time
- RAII cleanup (noexcept destructor)
- Error propagation from push loop to output stream
- ConversationItem-shaped response (content[0].text/transcript)

All 60 tests passing (57 unit + 3 E2E with real Nemotron model).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: ruiren_microsoft

sdk/cpp/CMakeLists.txt

@@ -0,0 +1,105 @@
+cmake_minimum_required(VERSION 3.14)
+project(foundry_local_cpp_sdk VERSION 1.0.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Options
+option(FOUNDRY_LOCAL_BUILD_TESTS "Build tests" ON)
+option(FOUNDRY_LOCAL_BUILD_E2E "Build E2E test (requires native core DLL)" OFF)
+
+# --------------------------------------------------------------------------
+# Dependencies via FetchContent
+# --------------------------------------------------------------------------
+include(FetchContent)
+
+FetchContent_Declare(
+    nlohmann_json
+    GIT_REPOSITORY https://github.com/nlohmann/json.git
+    GIT_TAG        v3.11.3
+)
+FetchContent_MakeAvailable(nlohmann_json)
+
+# --------------------------------------------------------------------------
+# Main SDK library
+# --------------------------------------------------------------------------
+add_library(foundry_local_sdk
+    src/core_interop_types.cpp
+    src/core_interop.cpp
+    src/live_audio_transcription_types.cpp
+    src/live_audio_transcription_session.cpp
+    src/audio_client.cpp
+)
+
+target_include_directories(foundry_local_sdk
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+)
+
+target_link_libraries(foundry_local_sdk
+    PUBLIC
+        nlohmann_json::nlohmann_json
+)
+
+# Platform-specific link dependencies
+if(WIN32)
+    # No extra libs needed — LoadLibraryW/GetProcAddress are in kernel32
+else()
+    target_link_libraries(foundry_local_sdk PRIVATE dl pthread)
+endif()
+
+# Compiler warnings
+if(MSVC)
+    target_compile_options(foundry_local_sdk PRIVATE /W4 /WX)
+else()
+    target_compile_options(foundry_local_sdk PRIVATE -Wall -Wextra -Werror -Wpedantic)
+endif()
+
+# --------------------------------------------------------------------------
+# Tests
+# --------------------------------------------------------------------------
+if(FOUNDRY_LOCAL_BUILD_TESTS)
+    enable_testing()
+
+    FetchContent_Declare(
+        googletest
+        GIT_REPOSITORY https://github.com/google/googletest.git
+        GIT_TAG        v1.14.0
+    )
+    # Prevent overriding parent project's compiler/linker settings on Windows
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+
+    # Unit tests
+    add_executable(foundry_local_tests
+        tests/test_live_audio_transcription_types.cpp
+        tests/test_thread_safe_queue.cpp
+        tests/test_live_audio_transcription_session.cpp
+    )
+
+    target_link_libraries(foundry_local_tests
+        PRIVATE
+            foundry_local_sdk
+            GTest::gtest_main
+    )
+
+    include(GoogleTest)
+    gtest_discover_tests(foundry_local_tests)
+
+    # E2E test (only built when native core is available)
+    if(FOUNDRY_LOCAL_BUILD_E2E)
+        add_executable(foundry_local_e2e_test
+            tests/test_e2e_live_audio.cpp
+        )
+
+        target_link_libraries(foundry_local_e2e_test
+            PRIVATE
+                foundry_local_sdk
+                GTest::gtest_main
+        )
+
+        gtest_discover_tests(foundry_local_e2e_test)
+    endif()
+endif()

sdk/cpp/README.md

@@ -0,0 +1,78 @@
+# Foundry Local C++ SDK — Live Audio Transcription
+
+C++ SDK for real-time audio streaming transcription using Foundry Local's native core.
+
+## API Overview
+
+```cpp
+#include "foundry_local/audio_client.h"
+#include "foundry_local/core_interop.h"
+
+// 1. Load native core
+auto core = std::make_shared<foundry_local::detail::CoreInterop>("path/to/Microsoft.AI.Foundry.Local.Core.dll");
+core->initialize({{"AppName", "my-app"}});
+
+// 2. Create audio client and session
+auto client = foundry_local::AudioClient("nemotron", core);
+auto session = client.create_live_transcription_session();
+
+// 3. Configure audio format (before start)
+session->settings().sample_rate = 16000;
+session->settings().channels = 1;
+session->settings().bits_per_sample = 16;
+session->settings().language = "en";
+
+// 4. Start session
+session->start();
+
+// 5. Push PCM audio chunks (thread-safe, from any thread)
+session->append(pcm_data, pcm_length);       // blocking if queue full
+session->try_append(pcm_data, pcm_length);   // non-blocking
+session->try_append_for(pcm_data, pcm_length, 100ms); // timed
+
+// 6. Read transcription results
+foundry_local::LiveAudioTranscriptionResponse result;
+auto status = session->try_get_next(result, std::chrono::seconds(5));
+if (status == foundry_local::TranscriptionStatus::result) {
+    std::cout << result.text << std::endl;
+    // Also available: result.content[0].text, result.content[0].transcript
+}
+
+// 7. Stop session (drains remaining audio, delivers final results)
+session->stop();
+// Or let RAII handle it — destructor calls stop()
+```
+
+## Building
+
+```bash
+mkdir build && cd build
+cmake .. -DFOUNDRY_LOCAL_BUILD_TESTS=ON
+cmake --build . --config Release
+ctest -C Release
+```
+
+### E2E Tests (requires native core DLL + model)
+
+```bash
+cmake .. -DFOUNDRY_LOCAL_BUILD_E2E=ON
+cmake --build . --config Release
+FOUNDRY_CORE_LIB_PATH=/path/to/libs ./Release/foundry_local_e2e_test
+```
+
+## Requirements
+
+- C++17 compiler (MSVC 2019+, GCC 9+, Clang 10+)
+- CMake 3.14+
+- Dependencies fetched automatically:
+  - [nlohmann/json](https://github.com/nlohmann/json) v3.11.3
+  - [GoogleTest](https://github.com/google/googletest) v1.14.0
+
+## Design Highlights
+
+- **Thread-safe push**: `append()` can be called from any thread (e.g., audio device callbacks)
+- **Bounded backpressure**: Internal push queue prevents unbounded memory growth
+- **Settings freeze**: Audio format settings are snapshot-copied at `start()` and immutable during the session
+- **RAII cleanup**: Destructor calls `stop()` in a best-effort, noexcept manner
+- **Error propagation**: Push-loop errors are surfaced through the output stream
+- **Full C# API parity**: Matches the C# LiveAudioTranscriptionSession from PR #485

sdk/cpp/codex.md

@@ -0,0 +1,100 @@
+# Codex Review Report — C++ Live Audio Transcription SDK
+
+## Summary
+
+C++ port of the C# LiveAudioTranscriptionSession (PR #485) with full API parity,
+60 passing tests (57 unit + 3 E2E), and verified real-time streaming through the
+native core with the Nemotron ASR model.
+
+## Issues Found & Resolved
+
+### 1. Response Type Parity (Fixed)
+- **Issue**: Initial implementation used flat `text` field instead of C#'s
+  `ConversationItem`-shaped `Content[0].Text` / `Content[0].Transcript`.
+- **Fix**: Added `ContentPart` struct with `text`/`transcript` aliasing.
+  Both flat `result.text` and structured `result.content[0].text` are available.
+
+### 2. Error State Preservation (Fixed)
+- **Issue**: `stop()` calling `output_queue_->close()` could overwrite a
+  push-loop error, silently converting a fatal ASR failure into a normal close.
+- **Fix**: `ThreadSafeQueue::close()` now preserves existing error state.
+  Test `PushErrorThenStop_PreservesError` validates this.
+
+### 3. Null Pointer Safety (Fixed)
+- **Issue**: `append(nullptr, n)` caused undefined behavior via
+  `std::vector<uint8_t>(nullptr, nullptr + n)`.
+- **Fix**: Added null guard — throws on `nullptr` with `length > 0`,
+  no-op for `length == 0`. Tests added.
+
+### 4. Queue Capacity Validation (Fixed)
+- **Issue**: `push_queue_capacity = 0` silently became unbounded;
+  negative values silently became huge via `static_cast<size_t>`.
+- **Fix**: `start()` validates `push_queue_capacity > 0` and throws.
+  Tests added for 0 and -1.
+
+## Performance Considerations
+
+- **Push loop latency**: Single `std::thread` per session, no thread pool.
+  Matches C#'s `Task.Run` approach. Adequate for real-time audio (typically
+  10-100ms chunk intervals).
+- **Memory copies**: Each `append()` copies the PCM buffer. Required for
+  safety (callers often reuse buffers in audio callbacks). Zero-copy would
+  require `std::span` with caller-guaranteed lifetime — not safe for the
+  general case.
+- **Queue contention**: `std::mutex` + `std::condition_variable` per queue.
+  Lock-free queues could reduce latency but add complexity without
+  measurable benefit at typical audio rates.
+
+## Concurrency Analysis
+
+- **Thread safety**: Verified via `ConcurrentAppendAndStop` test —
+  simultaneous push and stop from different threads completes without
+  deadlock or data corruption.
+- **State machine**: `not_started → started → stopping → stopped/failed`
+  transitions protected by `std::mutex`. No unguarded state access.
+- **Destructor**: `noexcept`, best-effort `stop()`, swallows exceptions.
+  Safe during stack unwinding.
+
+## Memory Safety
+
+- **RAII**: `ScopedResponse` wraps native `ResponseBuffer` and calls
+  `free_response` on destruction.
+- **Smart pointers**: `std::unique_ptr` for queues, `std::shared_ptr`
+  for `CoreInterop` (shared across sessions).
+- **Buffer lifetime**: Audio data copied in `append()`, original buffer
+  safe to reuse immediately.
+- **No raw `new`/`delete`**: All allocations via RAII wrappers.
+
+## Test Coverage Summary
+
+| Category | Tests | Status |
+|----------|-------|--------|
+| JSON deserialization | 8 | ✅ |
+| Options defaults | 1 | ✅ |
+| CoreErrorResponse | 3 | ✅ |
+| ThreadSafeQueue | 15 | ✅ |
+| Session state guards | 7 | ✅ |
+| Session lifecycle (mock) | 12 | ✅ |
+| CoreInteropRequest | 2 | ✅ |
+| TranscriptionStatus | 1 | ✅ |
+| Audit fixes (null, capacity, error) | 5 | ✅ |
+| Concurrency | 2 | ✅ |
+| Destructor | 1 | ✅ |
+| E2E (real core + model) | 3 | ✅ |
+| **Total** | **60** | **✅ All passing** |
+
+## Remaining Risks
+
+1. **Platform coverage**: Only tested on Windows (MSVC). Linux/macOS paths
+   exist in code but are untested. The `dlopen`/`dlsym` paths and library
+   extension logic should be validated on CI.
+
+2. **free_response availability**: The code falls back gracefully if
+   `free_response` is not exported by the native core, but relies on the
+   native core allocating response buffers with `Marshal.AllocHGlobal`
+   (Windows: `LocalFree`-compatible). If the native core changes its
+   allocation strategy, memory could leak.
+
+3. **Model loading**: The E2E test loads the Nemotron model directly via
+   `execute_command("load_model")`. A production SDK should integrate with
+   the full `FoundryLocalManager` lifecycle (catalog, download, cache, load).

sdk/cpp/include/foundry_local/audio_client.h

@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT License.
+
+#pragma once
+
+#include "core_interop.h"
+#include "live_audio_transcription_session.h"
+#include "live_audio_transcription_types.h"
+
+#include <memory>
+#include <string>
+
+namespace foundry_local {
+
+/// Audio client that provides audio transcription capabilities.
+/// Mirrors the C# OpenAIAudioClient API surface.
+class AudioClient {
+public:
+    /// @param model_id The model identifier for audio operations.
+    /// @param core_interop Shared pointer to the core interop layer.
+    AudioClient(const std::string& model_id,
+                std::shared_ptr<detail::CoreInterop> core_interop);
+
+    /// Create a real-time streaming transcription session.
+    /// Audio data is pushed in as PCM chunks and transcription results are
+    /// returned incrementally via the session's pull API.
+    /// @return A unique pointer to the transcription session.
+    std::unique_ptr<LiveAudioTranscriptionSession> create_live_transcription_session();
+
+private:
+    std::string model_id_;
+    std::shared_ptr<detail::CoreInterop> core_interop_;
+};
+
+} // namespace foundry_local