fix: orpheus TTS default + auto-port-fallback (1.0.0-alpha.2) (#72)

## Summary

Fixes two runtime errors that surfaced after installing `daemora@alpha`
and bumps the version so the next Publish run repoints npm `latest` at
the alpha.

- **Voice (Groq TTS 404 \`model_not_found\`)** — default model was
\`playai-tts-english\`, which never existed (the legacy id was
\`playai-tts\`) and \`playai-tts\` itself was sunset by Groq on
2025-12-23. Replaced default with \`canopylabs/orpheus-v1-english\` and
default voice \`troy\` (Orpheus accepts only \`[autumn, diana, hannah,
austin, daniel, troy]\`). Cleaned dead PlayAI entries out of
\`GroqTTS.ts\` sample-rate / voice maps. Updated the model picker in
\`providers.ts\` to expose Orpheus English + Arabic.
- **Server (EADDRINUSE on \`daemora start\`)** — if the configured port
(default 8081) is in use, the server now binds to port 0 (OS-assigned
random) instead of crashing. The actual bound port is read back from
\`server.address()\` and threaded through \`tunnel.start\`, the banner
URL, and \`autoOpen\` so the URL the user sees matches reality.
- **Version** — bumped \`package.json\` to \`1.0.0-alpha.2\`.
\`publish.yml\` already promotes whatever it publishes to the npm
\`latest\` dist-tag, so re-running the Publish workflow on \`main\`
after this merge will make plain \`npm install daemora\` resolve to the
alpha (currently \`latest\` still points at the old JS
\`2026.1.2-beta.2\`).

## Test plan

- [x] Merge to \`main\`
- [x] Run **Publish to npm** workflow with \`branch=main\`
- [x] Verify \`npm view daemora dist-tags\` shows \`latest:
1.0.0-alpha.2\`
- [x] \`npm install -g daemora\` (no \`@alpha\`) → \`daemora version\`
prints \`1.0.0-alpha.2\`
- [x] \`daemora start\` while another process holds 8081 → server binds
to a random port and prints a working URL
- [x] Voice worker starts → no \`Groq TTS 404 model_not_found\`; TTS
speaks via Orpheus

Author: UmarFarooq75

.github/workflows/publish.yml

@@ -156,6 +156,20 @@ jobs:
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
+      # Promote the just-published version to `latest` so plain
+      # `npm install daemora` (no tag) gets the new code. Without this,
+      # `latest` stays pinned to whatever stable was published before
+      # (e.g. 2026.1.2-beta.2) and pre-release publishes would only be
+      # reachable via `npm install daemora@alpha`.
+      - name: Promote to latest dist-tag
+        if: |
+          steps.config.outputs.skip != 'true' &&
+          inputs.dry_run != true
+        run: |
+          npm dist-tag add "daemora@${{ steps.config.outputs.version }}" latest
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Dry run (no publish)
         if: |
           steps.config.outputs.skip != 'true' &&

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "daemora",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Self-hosted AI agent platform — autonomous, multi-channel, multi-model.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package.json

@@ -6,6 +6,9 @@
  */
 
 import { exec } from "node:child_process";
+import type { Server } from "node:http";
+
+import type { Express } from "express";
 
 import { ChannelManager } from "../../channels/ChannelManager.js";
 import { ChannelRegistry } from "../../channels/ChannelRegistry.js";
@@ -374,15 +377,6 @@ export async function startCommand(): Promise<void> {
   let publicUrl = configuredPublic.length > 0
     ? configuredPublic.replace(/\/$/, "")
     : `http://localhost:${cfg.env.port}`;
-  if (!configuredPublic) {
-    tunnel.start({ port: cfg.env.port }).then((res) => {
-      if (res.kind !== "none") {
-        publicUrl = res.url;
-        log.info({ kind: res.kind, url: res.url }, "public URL updated from tunnel");
-      }
-    }).catch((e) => log.warn({ err: (e as Error).message }, "tunnel start crashed"));
-  }
-  log.info({ authEnabled, publicUrl }, "auth + webhooks ready");
 
   const app = createApp({
     cfg, agent, runner, sessions, memory, declarativeMemory,
@@ -398,19 +392,42 @@ export async function startCommand(): Promise<void> {
     customSkillsDir,
   });
 
-  const server = app.listen(cfg.env.port, () => {
-    const url = `http://localhost:${cfg.env.port}`;
-    const banner = box([
-      `Daemora-TS running at`,
-      `  ${url}`,
-      cfg.vault.exists() ? "Vault detected — unlock from the UI to start chatting." : "Open the URL above to set up your first provider.",
-    ]);
-    console.log("\n" + banner + "\n");
-
-    if (process.stdout.isTTY && !cfg.env.daemonMode && process.env["DAEMORA_NO_OPEN"] !== "1") {
-      autoOpen(url);
-    }
-  });
+  // Bind the HTTP server. If the configured port is already in use,
+  // fall back to an OS-assigned random port so `daemora start` never
+  // hard-fails just because something else is on 8081. The actual bound
+  // port is then threaded through tunnel/banner/autoOpen so the URL
+  // printed to the user matches reality.
+  const server = await listenWithFallback(app, cfg.env.port, log);
+  const addr = server.address();
+  const boundPort = typeof addr === "object" && addr ? addr.port : cfg.env.port;
+  if (boundPort !== cfg.env.port) {
+    log.warn({ requested: cfg.env.port, bound: boundPort }, "configured port in use — fell back to random port");
+  }
+  if (configuredPublic.length === 0) {
+    publicUrl = `http://localhost:${boundPort}`;
+  }
+
+  if (!configuredPublic) {
+    tunnel.start({ port: boundPort }).then((res) => {
+      if (res.kind !== "none") {
+        publicUrl = res.url;
+        log.info({ kind: res.kind, url: res.url }, "public URL updated from tunnel");
+      }
+    }).catch((e) => log.warn({ err: (e as Error).message }, "tunnel start crashed"));
+  }
+  log.info({ authEnabled, publicUrl, port: boundPort }, "auth + webhooks ready");
+
+  const url = `http://localhost:${boundPort}`;
+  const banner = box([
+    `Daemora-TS running at`,
+    `  ${url}`,
+    cfg.vault.exists() ? "Vault detected — unlock from the UI to start chatting." : "Open the URL above to set up your first provider.",
+  ]);
+  console.log("\n" + banner + "\n");
+
+  if (process.stdout.isTTY && !cfg.env.daemonMode && process.env["DAEMORA_NO_OPEN"] !== "1") {
+    autoOpen(url);
+  }
 
   const shutdown = (signal: NodeJS.Signals) => {
     log.info({ signal }, "shutting down");
@@ -461,6 +478,29 @@ function box(lines: readonly string[]): string {
   return `${top}\n${middle}\n${bot}`;
 }
 
+/**
+ * Bind the HTTP server to `port`. If that port is already in use,
+ * fall back to port 0 (OS-assigned random) instead of crashing —
+ * caller reads `server.address().port` to discover the actual port.
+ * Any other listen error (EACCES, etc.) is propagated as-is.
+ */
+function listenWithFallback(app: Express, port: number, log: { warn: (o: object, m: string) => void }): Promise<Server> {
+  return new Promise<Server>((resolve, reject) => {
+    const server = app.listen(port);
+    server.once("listening", () => resolve(server));
+    server.once("error", (err: NodeJS.ErrnoException) => {
+      if (err.code !== "EADDRINUSE") {
+        reject(err);
+        return;
+      }
+      log.warn({ port, err: err.message }, "port in use — retrying on a random port");
+      const fallback = app.listen(0);
+      fallback.once("listening", () => resolve(fallback));
+      fallback.once("error", reject);
+    });
+  });
+}
+
 function autoOpen(url: string): void {
   const cmd =
     process.platform === "darwin" ? `open "${url}"` :

src/cli/commands/start.ts

@@ -266,7 +266,8 @@ export const PROVIDER_CATALOG: readonly ProviderDef[] = [
       { id: "whisper-large-v3-turbo", name: "Whisper v3 Turbo", tier: "fast" },
     ],
     ttsModels: [
-      { id: "playai-tts", name: "Orpheus TTS", tier: "fast" },
+      { id: "canopylabs/orpheus-v1-english", name: "Orpheus v1 English", tier: "fast" },
+      { id: "canopylabs/orpheus-arabic-saudi", name: "Orpheus Arabic (Saudi)", tier: "fast" },
     ],
     ttsVoices: [
       { id: "troy", name: "Troy" }, { id: "hannah", name: "Hannah" },

src/models/providers.ts

@@ -21,15 +21,13 @@ import { type APIConnectOptions, AudioByteStream, tts } from "@livekit/agents";
 
 /**
  * Default per-model sample rates. Groq's `/v1/audio/speech` returns
- * WAV at different rates depending on the model — PlayAI is 48 kHz,
- * Orpheus is 24 kHz. If LiveKit is told the wrong rate, playback runs
- * at the wrong speed (24 kHz played as 48 kHz = double-speed chipmunk).
+ * WAV at 24 kHz for the current Orpheus models. (PlayAI was 48 kHz but
+ * was deprecated 2025-12-23.) If LiveKit is told the wrong rate, playback
+ * runs at the wrong speed (24 kHz played as 48 kHz = chipmunk).
  */
 const SAMPLE_RATE_BY_MODEL: Record<string, number> = {
-  "playai-tts": 48_000,
-  "playai-tts-english": 48_000,
-  "playai-tts-arabic": 48_000,
   "canopylabs/orpheus-v1-english": 24_000,
+  "canopylabs/orpheus-arabic-saudi": 24_000,
   "orpheus-v1-english": 24_000,
 };
 const DEFAULT_SAMPLE_RATE = 24_000;
@@ -38,23 +36,15 @@ const WAV_HEADER_BYTES = 44;
 
 /**
  * Default voice per Groq TTS model. Groq rejects requests without a voice
- * with `400 voice is required`, and the right voice depends on the model
- * family (PlayAI uses "Fritz-PlayAI" / "Celeste-PlayAI" / etc., Orpheus
- * uses "tara" / "leah" / etc.). Picking the wrong family also 400s, so a
- * single global default isn't safe — match by model.
+ * with `400 voice is required`. Orpheus accepts only the six voices in
+ * ORPHEUS_VOICES below — picking anything else 400s.
  */
 const DEFAULT_VOICE_BY_MODEL: Record<string, string> = {
-  "playai-tts": "Fritz-PlayAI",
-  "playai-tts-english": "Fritz-PlayAI",
-  "playai-tts-arabic": "Ahmad-PlayAI",
-  // Groq Orpheus accepts only [autumn, diana, hannah, austin, daniel, troy]
-  // — older "tara" / "leah" names from upstream Orpheus are rejected
-  // (400 invalid_request_error). Picking `troy` as a neutral male voice;
-  // override per-deploy via TTS_VOICE setting.
   "canopylabs/orpheus-v1-english": "troy",
+  "canopylabs/orpheus-arabic-saudi": "troy",
   "orpheus-v1-english": "troy",
 };
-const FALLBACK_VOICE = "Fritz-PlayAI";
+const FALLBACK_VOICE = "troy";
 
 /** Voices Groq's Orpheus model currently accepts. Used to validate TTS_VOICE. */
 const ORPHEUS_VOICES = new Set(["autumn", "diana", "hannah", "austin", "daniel", "troy"]);

src/voice/GroqTTS.ts

@@ -223,11 +223,15 @@ async function buildTTS(): Promise<ttsNs.TTS> {
       // pipeline.
       const apiKey = process.env["GROQ_API_KEY"];
       if (!apiKey) throw new Error("GROQ_API_KEY not set");
+      // Groq deprecated `playai-tts` on 2025-12-23; the current Groq TTS
+      // model is `canopylabs/orpheus-v1-english` (Orpheus). Default voice
+      // must be one of [autumn, diana, hannah, austin, daniel, troy] —
+      // anything else 400s.
       const { GroqTTS } = await import("./GroqTTS.js");
       return new GroqTTS({
         apiKey,
-        model: model ?? "playai-tts-english",
-        voice: voice ?? "Fritz-PlayAI",
+        model: model ?? "canopylabs/orpheus-v1-english",
+        voice: voice ?? "troy",
       });
     }
     case "openai":