feat(tts): per-tenant TTS config and per-agent voice override

- Add per-tenant TTS configuration endpoints (GET/POST /v1/tts/config)
  with RoleAdmin auth instead of master scope
- Implement TenantTTSResolver for channels to use tenant-specific
  TTS providers and auto mode settings
- Add per-agent voice override in channel TTS auto-apply:
  - Extend OutboundMessage with AgentID and AgentOtherConfig
  - Inject AgentAudioSnapshot in dispatch.go from outbound message
  - MaybeApply reads tts_voice_id/tts_model_id from agent context
- Fix events.go to use RunContext.TenantID directly (H3)
- Fix dispatch.go error notification to use sendCtx (H1)
- Update UI to use new /v1/tts/config endpoints

Author: viettranx

cmd/gateway_consumer_normal.go

@@ -233,7 +233,7 @@ func processNormalMessage(
 	blockReply := deps.ChannelMgr != nil && deps.ChannelMgr.ResolveBlockReply(msg.Channel, deps.Cfg.Gateway.BlockReply)
 	toolStatus := deps.Cfg.Gateway.ToolStatus == nil || *deps.Cfg.Gateway.ToolStatus // default true
 	if deps.ChannelMgr != nil {
-		deps.ChannelMgr.RegisterRun(runID, msg.Channel, chatIDForRun, messageID, outMeta, enableStream, blockReply, toolStatus)
+		deps.ChannelMgr.RegisterRun(runID, msg.Channel, chatIDForRun, messageID, outMeta, msg.TenantID, enableStream, blockReply, toolStatus)
 	}
 
 	// Group-aware system prompt: help the LLM adapt tone and behavior for group chats.
@@ -396,7 +396,7 @@ func processNormalMessage(
 	})
 
 	// Handle result asynchronously to not block the flush callback.
-	go func(agentKey, channel, chatID, session, rID, peerKind, inboundContent string, meta map[string]string, blockReplyEnabled bool, ptd *tools.PendingTeamDispatch) {
+	go func(agentKey, channel, chatID, session, rID, peerKind, inboundContent string, meta map[string]string, blockReplyEnabled bool, ptd *tools.PendingTeamDispatch, tenantID, agentUUID uuid.UUID, agentOtherConfig []byte) {
 		outcome := <-outCh
 
 		// Release team create lock — tasks already visible in DB, other goroutines can list.
@@ -426,6 +426,8 @@ func processNormalMessage(
 					ChatID:   chatID,
 					Content:  "",
 					Metadata: meta,
+					TenantID: tenantID,
+					AgentID:  agentUUID,
 				})
 				return
 			}
@@ -444,6 +446,8 @@ func processNormalMessage(
 				ChatID:   chatID,
 				Content:  errContent,
 				Metadata: meta,
+				TenantID: tenantID,
+				AgentID:  agentUUID,
 			})
 			return
 		}
@@ -461,6 +465,8 @@ func processNormalMessage(
 				ChatID:   chatID,
 				Content:  "",
 				Metadata: meta,
+				TenantID: tenantID,
+				AgentID:  agentUUID,
 			})
 			return
 		}
@@ -476,6 +482,8 @@ func processNormalMessage(
 				ChatID:   chatID,
 				Content:  "",
 				Metadata: meta,
+				TenantID: tenantID,
+				AgentID:  agentUUID,
 			})
 			return
 		}
@@ -491,10 +499,13 @@ func processNormalMessage(
 
 		// Publish response back to the channel
 		outMsg := bus.OutboundMessage{
-			Channel:  channel,
-			ChatID:   chatID,
-			Content:  replyContent,
-			Metadata: meta,
+			Channel:          channel,
+			ChatID:           chatID,
+			Content:          replyContent,
+			Metadata:         meta,
+			TenantID:         tenantID,
+			AgentID:          agentUUID,
+			AgentOtherConfig: agentOtherConfig,
 		}
 
 		appendMediaToOutbound(&outMsg, outcome.Result.Media)
@@ -505,5 +516,5 @@ func processNormalMessage(
 		if deps.TeamStore != nil && channel != tools.ChannelSystem && channel != tools.ChannelTeammate && channel != tools.ChannelDashboard {
 			go autoSetFollowup(ctx, deps.TeamStore, deps.AgentStore, agentKey, channel, chatID, replyContent)
 		}
-	}(agentID, msg.Channel, msg.ChatID, sessionKey, runID, peerKind, msg.Content, outMeta, blockReply, ptd)
+	}(agentID, msg.Channel, msg.ChatID, sessionKey, runID, peerKind, msg.Content, outMeta, blockReply, ptd, msg.TenantID, agentLoop.UUID(), agentLoop.OtherConfig())
 }

cmd/gateway_http_wiring.go

@@ -254,10 +254,21 @@ func (d *gatewayDeps) wireHTTPHandlersOnServer(
 		if rl := d.server.RateLimiter(); rl != nil && rl.Enabled() {
 			ttsH.SetRateLimiter(rl.Allow)
 		}
+		// Wire stores for per-tenant TTS config lookup at synthesis time.
+		if d.pgStores.SystemConfigs != nil && d.pgStores.ConfigSecrets != nil {
+			ttsH.SetStores(d.pgStores.SystemConfigs, d.pgStores.ConfigSecrets)
+			// Wire tenant resolver for channels TTS auto-apply
+			d.audioMgr.SetTenantResolver(httpapi.NewTenantTTSResolver(d.pgStores.SystemConfigs, d.pgStores.ConfigSecrets))
+		}
 		d.server.SetTTSHandler(ttsH)
 		d.ttsHandler = ttsH // store for hot-reload
 	}
 
+	// Per-tenant TTS config endpoint — allows tenant admins to configure TTS.
+	if d.pgStores.SystemConfigs != nil && d.pgStores.ConfigSecrets != nil {
+		d.server.SetTTSConfigHandler(httpapi.NewTTSConfigHandler(d.pgStores.SystemConfigs, d.pgStores.ConfigSecrets))
+	}
+
 	// Seed + apply builtin tool disables
 	if d.pgStores.BuiltinTools != nil {
 		seedBuiltinTools(context.Background(), d.pgStores.BuiltinTools)

internal/agent/loop_tracing.go

@@ -32,6 +32,10 @@ func (l *Loop) ID() string { return l.id }
 // See docs/agent-identity-conventions.md.
 func (l *Loop) UUID() uuid.UUID { return l.agentUUID }
 
+// OtherConfig returns the agent's other_config JSONB (extensibility bag).
+// Used for per-agent TTS voice override (tts_voice_id, tts_model_id).
+func (l *Loop) OtherConfig() json.RawMessage { return l.agentOtherConfig }
+
 // Model returns the model identifier for this agent loop.
 func (l *Loop) Model() string { return l.model }
 

internal/agent/router_cache_canonicalize_test.go

@@ -2,6 +2,7 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"strings"
 	"sync/atomic"
 	"testing"
@@ -21,6 +22,8 @@ type stubAgent struct {
 }
 
 func (s *stubAgent) ID() string                                          { return s.id }
+func (s *stubAgent) UUID() uuid.UUID                                     { return uuid.Nil }
+func (s *stubAgent) OtherConfig() json.RawMessage                        { return nil }
 func (s *stubAgent) Run(context.Context, RunRequest) (*RunResult, error) { return nil, nil }
 func (s *stubAgent) IsRunning() bool                                     { return s.running }
 func (s *stubAgent) Model() string                                       { return "test-model" }

internal/agent/types.go

@@ -2,6 +2,9 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
+
+	"github.com/google/uuid"
 
 	"github.com/nextlevelbuilder/goclaw/internal/providers"
 )
@@ -10,6 +13,8 @@ import (
 // Implemented by *Loop; extracted as an interface for testability and composability.
 type Agent interface {
 	ID() string
+	UUID() uuid.UUID
+	OtherConfig() json.RawMessage
 	Run(ctx context.Context, req RunRequest) (*RunResult, error)
 	IsRunning() bool
 	Model() string

internal/audio/auto_apply_helper.go

@@ -0,0 +1,62 @@
+package audio
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// AutoApplyResult holds the result of TTS auto-apply processing.
+type AutoApplyResult struct {
+	// Text is the message content with [[tts]] directives stripped.
+	Text string
+	// AudioPath is the path to generated audio file (empty if no TTS applied).
+	AudioPath string
+	// AudioMime is the MIME type of generated audio (e.g. "audio/ogg").
+	AudioMime string
+}
+
+// AutoApplyToText checks if TTS should be auto-applied to the message content.
+// Returns modified text (directives stripped) and audio path if TTS was applied.
+// channel: "telegram", "discord", etc. - used for format selection (opus for telegram).
+// isVoiceInbound: true if user sent voice message (for "inbound" auto mode).
+// workspace: directory to save generated audio files.
+func (m *Manager) AutoApplyToText(
+	ctx context.Context,
+	content string,
+	channel string,
+	isVoiceInbound bool,
+	workspace string,
+) (*AutoApplyResult, error) {
+	if m == nil || content == "" {
+		return &AutoApplyResult{Text: content}, nil
+	}
+
+	// Check if TTS should be applied (respects auto mode: off/always/inbound/tagged)
+	result, ok := m.MaybeApply(ctx, content, channel, isVoiceInbound, "final")
+	if !ok || result == nil {
+		return &AutoApplyResult{Text: StripTTSDirectives(content)}, nil
+	}
+
+	// Write audio to workspace/tts/ directory
+	ttsDir := workspace
+	if ttsDir == "" {
+		ttsDir = os.TempDir()
+	}
+	ttsDir = filepath.Join(ttsDir, "tts")
+	if err := os.MkdirAll(ttsDir, 0755); err != nil {
+		return &AutoApplyResult{Text: StripTTSDirectives(content)}, err
+	}
+
+	audioPath := filepath.Join(ttsDir, "auto-"+time.Now().Format("20060102-150405")+"."+result.Extension)
+	if err := os.WriteFile(audioPath, result.Audio, 0644); err != nil {
+		return &AutoApplyResult{Text: StripTTSDirectives(content)}, err
+	}
+
+	return &AutoApplyResult{
+		Text:      StripTTSDirectives(content),
+		AudioPath: audioPath,
+		AudioMime: result.MimeType,
+	}, nil
+}

internal/audio/manager.go

@@ -23,6 +23,11 @@ func channelFromCtx(ctx context.Context) string {
 	return v
 }
 
+// TenantTTSResolver resolves per-tenant TTS provider and config.
+// Returns (provider, providerName, autoMode, error). If error is non-nil,
+// caller should fall back to global manager config.
+type TenantTTSResolver func(ctx context.Context) (TTSProvider, string, AutoMode, error)
+
 // Manager orchestrates audio providers across TTS, STT, Music, and SFX
 // operations. Each op has its own provider map + primary/fallback chain.
 //
@@ -43,6 +48,8 @@ type Manager struct {
 	mode      Mode
 	maxLength int // max text length before truncation (default 1500)
 	timeoutMs int // provider timeout (default 30000)
+
+	tenantResolver TenantTTSResolver // per-tenant TTS config resolver (nil = use global)
 }
 
 // ManagerConfig configures the audio manager. Preserved from legacy TTS
@@ -126,6 +133,23 @@ func (m *Manager) GetProvider(name string) (TTSProvider, bool) {
 // PrimaryProvider returns the primary TTS provider name.
 func (m *Manager) PrimaryProvider() string { return m.primary }
 
+// SetTenantResolver sets the per-tenant TTS config resolver.
+// Channels use this to resolve tenant-specific TTS providers.
+func (m *Manager) SetTenantResolver(r TenantTTSResolver) { m.tenantResolver = r }
+
+// ResolveTenantProvider attempts to get tenant-specific TTS provider.
+// Returns (provider, name, autoMode, ok). If ok=false, caller uses global config.
+func (m *Manager) ResolveTenantProvider(ctx context.Context) (TTSProvider, string, AutoMode, bool) {
+	if m.tenantResolver == nil {
+		return nil, "", "", false
+	}
+	p, name, auto, err := m.tenantResolver(ctx)
+	if err != nil {
+		return nil, "", "", false
+	}
+	return p, name, auto, true
+}
+
 // AutoMode returns the current auto-apply mode.
 func (m *Manager) AutoMode() AutoMode { return m.auto }
 

internal/audio/manager_auto.go

@@ -2,8 +2,11 @@ package audio
 
 import (
 	"context"
+	"encoding/json"
 	"log/slog"
 	"strings"
+
+	"github.com/nextlevelbuilder/goclaw/internal/store"
 )
 
 // MaybeApply inspects auto-mode and conditionally applies TTS to a reply.
@@ -16,7 +19,15 @@ import (
 //   - isVoiceInbound: whether the user's inbound message was voice
 //   - kind: "tool", "block", or "final"
 func (m *Manager) MaybeApply(ctx context.Context, text, channel string, isVoiceInbound bool, kind string) (*SynthResult, bool) {
-	if m.auto == AutoOff {
+	// Try tenant-specific TTS config first
+	tenantProvider, _, tenantAuto, hasTenant := m.ResolveTenantProvider(ctx)
+
+	auto := m.auto
+	if hasTenant && tenantAuto != "" {
+		auto = tenantAuto
+	}
+
+	if auto == AutoOff {
 		return nil, false
 	}
 
@@ -25,7 +36,7 @@ func (m *Manager) MaybeApply(ctx context.Context, text, channel string, isVoiceI
 		return nil, false
 	}
 
-	switch m.auto {
+	switch auto {
 	case AutoInbound:
 		if !isVoiceInbound {
 			return nil, false
@@ -42,7 +53,7 @@ func (m *Manager) MaybeApply(ctx context.Context, text, channel string, isVoiceI
 
 	// Content validation (matches legacy TTS behavior).
 	cleanText := stripMarkdown(text)
-	cleanText = stripTtsDirectives(cleanText)
+	cleanText = StripTTSDirectives(cleanText)
 	cleanText = strings.TrimSpace(cleanText)
 
 	if len(cleanText) < 10 {
@@ -61,7 +72,32 @@ func (m *Manager) MaybeApply(ctx context.Context, text, channel string, isVoiceI
 		opts.Format = "opus" // Telegram voice bubbles need opus
 	}
 
-	result, err := m.SynthesizeWithFallback(ctx, cleanText, opts)
+	// Apply per-agent voice/model override from context (set by dispatch.go from OutboundMessage)
+	if snap, ok := store.AgentAudioFromCtx(ctx); ok && len(snap.OtherConfig) > 0 {
+		var agentCfg struct {
+			TTSVoiceID string `json:"tts_voice_id,omitempty"`
+			TTSModelID string `json:"tts_model_id,omitempty"`
+		}
+		if err := json.Unmarshal(snap.OtherConfig, &agentCfg); err == nil {
+			if agentCfg.TTSVoiceID != "" {
+				opts.Voice = agentCfg.TTSVoiceID
+			}
+			if agentCfg.TTSModelID != "" {
+				opts.Model = agentCfg.TTSModelID
+			}
+		}
+	}
+
+	var result *SynthResult
+	var err error
+
+	// Use tenant provider if available, otherwise fall back to global
+	if hasTenant && tenantProvider != nil {
+		result, err = tenantProvider.Synthesize(ctx, cleanText, opts)
+	} else {
+		result, err = m.SynthesizeWithFallback(ctx, cleanText, opts)
+	}
+
 	if err != nil {
 		slog.Warn("tts auto-apply failed", "error", err)
 		return nil, false

internal/bus/types.go

@@ -35,11 +35,14 @@ type InboundMessage struct {
 
 // OutboundMessage represents a message to be sent to a channel.
 type OutboundMessage struct {
-	Channel  string            `json:"channel"`
-	ChatID   string            `json:"chat_id"`
-	Content  string            `json:"content"`
-	Media    []MediaAttachment `json:"media,omitempty"`    // optional media attachments
-	Metadata map[string]string `json:"metadata,omitempty"` // channel-specific metadata
+	Channel         string            `json:"channel"`
+	ChatID          string            `json:"chat_id"`
+	Content         string            `json:"content"`
+	Media           []MediaAttachment `json:"media,omitempty"`              // optional media attachments
+	Metadata        map[string]string `json:"metadata,omitempty"`           // channel-specific metadata
+	TenantID        uuid.UUID         `json:"tenant_id,omitempty"`          // tenant scope for per-tenant TTS
+	AgentID         uuid.UUID         `json:"agent_id,omitempty"`           // agent scope for per-agent TTS voice override
+	AgentOtherConfig []byte           `json:"agent_other_config,omitempty"` // agent's other_config for TTS voice/model
 }
 
 // MediaAttachment represents a media file to be sent with a message.