Merge pull request #9 from gaelic-ghost/release/speakswiftly-3-3-0-backend-surfaces

release: prepare v3.3.0

Author: gaelic-ghost

.codex/hooks/stop-tts.mjs

@@ -15,6 +15,7 @@ const runtimeBaseUrl = process.env.CODEX_HOOK_TTS_BASE_URL ?? "http://127.0.0.1:
 const liveSpeechEndpoint = new URL("/speech/live", runtimeBaseUrl).toString();
 const defaultProfileName = process.env.CODEX_HOOK_TTS_PROFILE_NAME ?? "default-femme";
 const skipContinuedTurns = (process.env.CODEX_HOOK_TTS_SKIP_CONTINUATIONS ?? "true") !== "false";
+const logFullPayload = (process.env.CODEX_HOOK_TTS_LOG_FULL_PAYLOAD ?? "true") !== "false";
 const maxSeenTurns = Number.parseInt(process.env.CODEX_HOOK_TTS_MAX_SEEN_TURNS ?? "200", 10);
 
 async function readStdin() {
@@ -58,6 +59,14 @@ function normalizeMessage(input) {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function payloadLogFields(rawInput, payload) {
+  if (!logFullPayload) return {};
+  return {
+    rawPayload: rawInput,
+    payload,
+  };
+}
+
 async function main() {
   await ensureRuntimePaths();
 
@@ -72,6 +81,7 @@ async function main() {
     cwd = process.cwd(),
     model = null,
   } = payload;
+  const fullPayloadLog = payloadLogFields(rawInput, payload);
 
   const message = normalizeMessage(lastAssistantMessage);
   const dedupeKey = sessionId && turnId ? `${sessionId}:${turnId}` : null;
@@ -86,6 +96,7 @@ async function main() {
       transcriptPath,
       cwd,
       model,
+      ...fullPayloadLog,
     });
     return;
   }
@@ -101,6 +112,7 @@ async function main() {
       cwd,
       model,
       preview: message.slice(0, 160),
+      ...fullPayloadLog,
     });
     return;
   }
@@ -117,6 +129,7 @@ async function main() {
       cwd,
       model,
       preview: message.slice(0, 160),
+      ...fullPayloadLog,
     });
     return;
   }
@@ -149,6 +162,7 @@ async function main() {
       profileName: defaultProfileName,
       endpoint: liveSpeechEndpoint,
       preview: message.slice(0, 160),
+      ...fullPayloadLog,
     });
     return;
   }
@@ -177,15 +191,18 @@ async function main() {
     profileName: defaultProfileName,
     request: parsedResponse,
     preview: message.slice(0, 160),
+    ...fullPayloadLog,
   });
 }
 
 main().catch(async (error) => {
   try {
     await ensureRuntimePaths();
+    const rawInput = await readStdin().catch(() => "");
     await appendLog({
       outcome: "error",
       reason: "unexpected-hook-failure",
+      ...(logFullPayload ? { rawPayload: rawInput } : {}),
       error: error instanceof Error ? { message: error.message, stack: error.stack } : String(error),
     });
   } catch {}

Package.resolved

@@ -31,7 +31,7 @@ let package = Package(
         .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
         .package(
             url: "https://github.com/gaelic-ghost/SpeakSwiftly.git",
-            from: "3.0.5",
+            from: "3.0.6",
         ),
         .package(url: "https://github.com/ml-explore/mlx-swift-lm.git", exact: "2.30.6"),
         .package(url: "https://github.com/gaelic-ghost/TextForSpeech.git", from: "0.17.0"),

Package.swift

@@ -38,7 +38,7 @@ The package stays intentionally narrow. Hummingbird owns transport hosting, `Spe
 
 ### Current SpeakSwiftly Alignment
 
-This server is aligned to the current public library surface of its resolved [`SpeakSwiftly`](https://github.com/gaelic-ghost/SpeakSwiftly) `3.0.5` package dependency.
+This server is aligned to the current public library surface of its resolved [`SpeakSwiftly`](https://github.com/gaelic-ghost/SpeakSwiftly) `3.0.6` package dependency.
 
 Today the server relies on the current typed runtime capabilities that matter for transport hosting:
 
@@ -98,11 +98,13 @@ That alignment means the remaining translation layer is intentionally transport-
 
 For generation requests, the server also supports one server-owned default voice profile. HTTP and MCP callers may omit `profile_name` for live speech, retained audio, and retained batch requests when the server has `app.defaultVoiceProfileName` or `APP_DEFAULT_VOICE_PROFILE_NAME` configured. When neither the request nor the server configuration provides a voice profile, the server rejects the request with a descriptive validation error instead of silently guessing.
 
+Across the HTTP, MCP, tool-catalog, and embedded control surfaces, the server now publishes the normalized backend identifiers `qwen3`, `chatterbox_turbo`, and `marvis`. Compatibility input using the older `qwen3_custom_voice` backend name is still accepted on transport-facing runtime-control requests and is normalized to `qwen3` before persistence or response shaping.
+
 That narrowness also informs platform policy. The package should prefer maintainable Apple-platform architecture for the current macOS and near-future iOS use cases over speculative cross-platform compromises.
 
 ## Setup
 
-This package resolves its SwiftPM dependencies from GitHub source control in [`Package.swift`](https://github.com/gaelic-ghost/SpeakSwiftlyServer/blob/main/Package.swift) and locks the resolved revisions in [`Package.resolved`](https://github.com/gaelic-ghost/SpeakSwiftlyServer/blob/main/Package.resolved). `SpeakSwiftly` uses a normal semantic-version requirement here, and this package currently follows it with an up-to-next-major constraint starting at `3.0.5`. The server's direct `TextForSpeech` dependency now tracks `0.17.0`, matching the current upstream `SpeakSwiftly` graph.
+This package resolves its SwiftPM dependencies from GitHub source control in [`Package.swift`](https://github.com/gaelic-ghost/SpeakSwiftlyServer/blob/main/Package.swift) and locks the resolved revisions in [`Package.resolved`](https://github.com/gaelic-ghost/SpeakSwiftlyServer/blob/main/Package.resolved). `SpeakSwiftly` uses a normal semantic-version requirement here, and this package currently follows it with an up-to-next-major constraint starting at `3.0.6`. The server's direct `TextForSpeech` dependency now tracks `0.17.0`, matching the current upstream `SpeakSwiftly` graph.
 
 Build the package with SwiftPM through Xcode's selected toolchain:
 

README.md

@@ -3,6 +3,20 @@ import Hummingbird
 import SpeakSwiftly
 import TextForSpeech
 
+// MARK: - Speech Backend Surface Helpers
+
+func exposedSpeechBackendIdentifiers() -> [String] {
+    SpeakSwiftly.SpeechBackend.allCases.map(\.rawValue)
+}
+
+func supportedSpeechBackendDescription() -> String {
+    exposedSpeechBackendIdentifiers().joined(separator: ", ")
+}
+
+func legacySpeechBackendNormalizationNote() -> String {
+    "The legacy value '\(SpeakSwiftly.SpeechBackend.legacyQwenCustomVoiceRawValue)' is still accepted and normalized to 'qwen3'."
+}
+
 // MARK: - SpeakRequestPayload
 
 struct SpeakRequestPayload: Decodable {
@@ -303,11 +317,10 @@ private func resolveSpeechBackend(
     _ rawValue: String,
     fieldName: String,
 ) throws -> SpeakSwiftly.SpeechBackend {
-    guard let speechBackend = SpeakSwiftly.SpeechBackend(rawValue: rawValue) else {
-        let supportedBackends = SpeakSwiftly.SpeechBackend.allCases.map(\.rawValue).joined(separator: ", ")
+    guard let speechBackend = SpeakSwiftly.SpeechBackend.normalized(rawValue: rawValue) else {
         throw HTTPError(
             .badRequest,
-            message: "Runtime configuration field '\(fieldName)' used unsupported value '\(rawValue)'. Expected one of: \(supportedBackends).",
+            message: "Runtime configuration field '\(fieldName)' used unsupported value '\(rawValue)'. Expected one of: \(supportedSpeechBackendDescription()). \(legacySpeechBackendNormalizationNote())",
         )
     }
 

Sources/SpeakSwiftlyServer/Host/ServerModels.swift

@@ -149,7 +149,7 @@ enum MCPToolCatalog {
                 "type": "object",
                 "required": ["speech_backend"],
                 "properties": [
-                    "speech_backend": ["type": "string", "enum": ["qwen3", "marvis"]],
+                    "speech_backend": ["type": "string", "enum": ["qwen3", "chatterbox_turbo", "marvis"]],
                 ],
             ],
         ),
@@ -160,7 +160,7 @@ enum MCPToolCatalog {
                 "type": "object",
                 "required": ["speech_backend"],
                 "properties": [
-                    "speech_backend": ["type": "string", "enum": ["qwen3", "marvis"]],
+                    "speech_backend": ["type": "string", "enum": ["qwen3", "chatterbox_turbo", "marvis"]],
                 ],
             ],
         ),

Sources/SpeakSwiftlyServer/MCP/MCPToolCatalog.swift

@@ -139,10 +139,9 @@ func requiredSpeechBackend(
     in arguments: [String: Value],
 ) throws -> SpeakSwiftly.SpeechBackend {
     let rawValue = try requiredString(key, in: arguments)
-    guard let speechBackend = SpeakSwiftly.SpeechBackend(rawValue: rawValue) else {
-        let acceptedValues = SpeakSwiftly.SpeechBackend.allCases.map(\.rawValue).joined(separator: ", ")
+    guard let speechBackend = SpeakSwiftly.SpeechBackend.normalized(rawValue: rawValue) else {
         throw MCPError.invalidParams(
-            "Tool argument '\(key)' used unsupported value '\(rawValue)'. Expected one of: \(acceptedValues).",
+            "Tool argument '\(key)' used unsupported value '\(rawValue)'. Expected one of: \(supportedSpeechBackendDescription()). \(legacySpeechBackendNormalizationNote())",
         )
     }
 

Sources/SpeakSwiftlyServer/MCP/MCPToolSupport.swift

@@ -72,6 +72,28 @@ extension ServerTests {
             #expect(updateRuntimeConfigJSON["persisted_speech_backend"] as? String == "marvis")
             #expect(updateRuntimeConfigJSON["persisted_configuration_state"] as? String == "loaded")
 
+            let updateChatterboxRuntimeConfigResponse = try await client.execute(
+                uri: "/runtime/configuration",
+                method: .put,
+                headers: [.contentType: "application/json"],
+                body: byteBuffer(#"{"speech_backend":"chatterbox_turbo"}"#),
+            )
+            let updateChatterboxRuntimeConfigJSON = try jsonObject(from: updateChatterboxRuntimeConfigResponse.body)
+            #expect(updateChatterboxRuntimeConfigResponse.status == .ok)
+            #expect(updateChatterboxRuntimeConfigJSON["next_runtime_speech_backend"] as? String == "chatterbox_turbo")
+            #expect(updateChatterboxRuntimeConfigJSON["persisted_speech_backend"] as? String == "chatterbox_turbo")
+
+            let updateLegacyQwenRuntimeConfigResponse = try await client.execute(
+                uri: "/runtime/configuration",
+                method: .put,
+                headers: [.contentType: "application/json"],
+                body: byteBuffer(#"{"speech_backend":"qwen3_custom_voice"}"#),
+            )
+            let updateLegacyQwenRuntimeConfigJSON = try jsonObject(from: updateLegacyQwenRuntimeConfigResponse.body)
+            #expect(updateLegacyQwenRuntimeConfigResponse.status == .ok)
+            #expect(updateLegacyQwenRuntimeConfigJSON["next_runtime_speech_backend"] as? String == "qwen3")
+            #expect(updateLegacyQwenRuntimeConfigJSON["persisted_speech_backend"] as? String == "qwen3")
+
             let profilesResponse = try await client.execute(uri: "/voices", method: .get)
             let profilesJSON = try jsonObject(from: profilesResponse.body)
             let profiles = try #require(profilesJSON["profiles"] as? [[String: Any]])
@@ -357,7 +379,9 @@ extension ServerTests {
             #expect(persistMessage.contains("speech_backend"))
             #expect(persistMessage.contains("totally_invalid"))
             #expect(persistMessage.contains("qwen3"))
+            #expect(persistMessage.contains("chatterbox_turbo"))
             #expect(persistMessage.contains("marvis"))
+            #expect(persistMessage.contains("qwen3_custom_voice"))
 
             let switchResponse = try await client.execute(
                 uri: "/runtime/backend",
@@ -372,7 +396,9 @@ extension ServerTests {
             #expect(switchMessage.contains("speech_backend"))
             #expect(switchMessage.contains("totally_invalid"))
             #expect(switchMessage.contains("qwen3"))
+            #expect(switchMessage.contains("chatterbox_turbo"))
             #expect(switchMessage.contains("marvis"))
+            #expect(switchMessage.contains("qwen3_custom_voice"))
         }
 
         await host.shutdown()

Tests/SpeakSwiftlyServerTests/HTTPWorkflowTests.swift

@@ -399,10 +399,10 @@ import Testing
     #expect(await host.defaultVoiceProfileName() == nil)
     #expect(await host.resolvedRequestedVoiceProfileName(nil) == nil)
 
-    let switchedSnapshot = try await state.switchSpeechBackend(to: .marvis)
-    #expect(switchedSnapshot.runtimeConfiguration.activeRuntimeSpeechBackend == "marvis")
+    let switchedSnapshot = try await state.switchSpeechBackend(to: .chatterboxTurbo)
+    #expect(switchedSnapshot.runtimeConfiguration.activeRuntimeSpeechBackend == "chatterbox_turbo")
     let runtimeConfigurationAfterSwitch = await MainActor.run { state.runtimeConfiguration }
-    #expect(runtimeConfigurationAfterSwitch.activeRuntimeSpeechBackend == "marvis")
+    #expect(runtimeConfigurationAfterSwitch.activeRuntimeSpeechBackend == "chatterbox_turbo")
 
     let reloadedSnapshot = try await state.reloadModels()
     #expect(reloadedSnapshot.overview.workerStage == "resident_model_ready")

Tests/SpeakSwiftlyServerTests/HostStateTests.swift

@@ -28,6 +28,12 @@ extension ServerTests {
             #expect(tools.contains { $0["name"] as? String == "get_staged_runtime_config" })
             #expect(tools.contains { $0["name"] as? String == "set_staged_config" })
             #expect(tools.contains { $0["name"] as? String == "get_runtime_overview" })
+            let setStagedConfigTool = try #require(tools.first { $0["name"] as? String == "set_staged_config" })
+            let setStagedConfigSchema = try #require(setStagedConfigTool["inputSchema"] as? [String: Any])
+            let setStagedConfigProperties = try #require(setStagedConfigSchema["properties"] as? [String: Any])
+            let setStagedConfigBackend = try #require(setStagedConfigProperties["speech_backend"] as? [String: Any])
+            let setStagedConfigBackendEnum = try #require(setStagedConfigBackend["enum"] as? [String])
+            #expect(setStagedConfigBackendEnum == ["qwen3", "chatterbox_turbo", "marvis"])
 
             let listResourcesEnvelope = try await mcpEnvelope(
                 from: mcpSurface.handle(