<!-- status: done -->
<!-- started: 2026-04-23 -->
<!-- completed: 2026-04-24 -->
<!-- component: gateway, frontend-nyla, teams-bot -->

<!--
  Vollstaendig umgesetzt: Datamodel, Interface-CRUD, _activeServices-Registry,
  submit/_processDirectorPrompt + _runAgentForMeeting, Reconnect-Persistenz,
  Hybrid-Routing (needsAgent), SystemPrompt mit Eskalations-Regeln, Routes
  POST/GET/DELETE mit RBAC + Limits + Rate-Limit, Frontend-API + SSE-Listener
  + UDB-Sidebar + Regie-Panel + CSS. 26 Backend-Unit-Tests gruen
  (gateway/tests/unit/teamsbot/test_directorPrompts.py). AC 5 + 6 abgedeckt;
  AC 1-4 sind manuelle Live-Meeting-Tests.

  b-reference: teams-bot/architecture.md (Hybrid + Director Prompts) und
  gateway/ai-agent.md (Teamsbot-Integration, kein eigenes Toolset) sind
  aktualisiert; TOPICS.md gepflegt.
-->

# Teamsbot Regieanweisungen (Director Prompts)

## Beschreibung und Kontext

Der Teamsbot laeuft heute auf einem hochspezialisierten, schnellen Pfad
(`OperationTypeEnum.SPEECH_TEAMS`), der reaktiv auf Sprache reagiert.
Der Operator soll dem Bot waehrend des Meetings *privat* Anweisungen geben
koennen ("Recherchiere das gerade diskutierte Thema und gib eine Empfehlung",
"Lies die Datei XY vor", "Schreib das ins Chat"). Diese **Regieanweisungen**
sind fuer die anderen Teilnehmer unsichtbar und triggern den Bot sofort,
unabhaengig von Cooldowns oder Sprach-Triggern.

Long-term-clean: Voller Agent-Pfad mit RAG, Datenschnittstellen, Toolboxen.

## Fokus und kritische Details

- **Hybrid-Routing**: `SPEECH_TEAMS` bleibt der schnelle Default-Pfad.
  Der Agent (`agentService.runAgent`) wird nur fuer (a) Director Prompts und
  (b) `SPEECH_TEAMS`-Eskalation (`needsAgent=true`) verwendet.
- **Privacy**: Director-Prompts werden in der DB gespeichert und ueber SSE
  ausschliesslich an den Operator (Eigentuemer der Session) ausgeliefert.
- **Kein neues Teamsbot-Toolset**: Der Agent verwendet bestehende Core-Tools
  (`webSearch`, `readUrl`, `sendMail`, `renderDocument`, `requestToolbox`,
  Datenschnittstellen-Tools etc.). Sein finaler `FINAL`-Event-Text wird wie
  eine `SPEECH_TEAMS`-Antwort ueber TTS+Chat ans Meeting ausgeliefert.
- **Persistenz**: Persistente Director-Prompts werden bei jedem Trigger
  (SPEECH_TEAMS und neuer Director-Prompt) als zusaetzlicher Kontext in den
  System-Prompt gemischt, bis der Operator sie loescht.
- **Service-Registry**: Damit eine HTTP-Route auf die laufende WS-Session
  zugreifen kann, registriert `handleBotWebSocket` den `TeamsbotService` mit
  `websocket` + `voiceInterface` modul-weit.

## Ziel und Nicht-Ziele

- Ziel: Operator kann private Text-Prompts (mit optional UDB-Files) an den
  laufenden Bot senden; Bot fuehrt Agent-Run aus, antwortet ins Meeting per
  TTS/Chat und kann Tools (Web, Mail, SharePoint, ...) nutzen.
- Ziel: SPEECH_TEAMS kann selbststaendig signalisieren `needsAgent=true`,
  damit komplexe Spoken-Requests (z. B. "recherchier das im Internet") den
  Agent triggern, statt nur eine Floskel zurueckzugeben.
- Nicht-Ziel: Eigene Teamsbot-spezifische Tools fuer den Agent (sendChat,
  readAloud) — diese bleiben im SPEECH_TEAMS-Pfad als `commands`. Der Agent
  spricht nur ueber seinen Final-Text, der vom Service ausgeliefert wird.
- Nicht-Ziel: PDF-Anhang in Teams-Chat (Browser-Bot-Limit). Stattdessen wird
  der vom Agent generierte Link gepostet.

## Betroffene Module

- Gateway: `modules/features/teamsbot/datamodelTeamsbot.py`,
  `interfaceFeatureTeamsbot.py`, `service.py`, `routeFeatureTeamsbot.py`,
  `modules/serviceCenter/services/serviceAi/mainServiceAi.py`
- Frontend: `src/api/teamsbotApi.ts`, `src/pages/views/teamsbot/TeamsbotSessionView.tsx`,
  `src/pages/views/teamsbot/Teamsbot.module.css`
- DB-Migration: ja (neue Tabelle `teamsbotDirectorPrompts` via `registerDatabase`/Auto-Migrate)
- Andere: `service-teams-browser-bot` — keine Aenderungen (Agent nutzt
  bestehende WS-Commands `sendChatMessage`, `playAudio`).

## Architektur

```mermaid
flowchart LR
    UI["Operator UI (Regie-Panel + UDB)"] -- POST directorPrompt --> Route["routeFeatureTeamsbot"]
    Route -- submitDirectorPrompt --> Svc["TeamsbotService (active)"]
    Svc -- runAgent --> Agent["agentService.runAgent (toolSet=core, web aktiv, maxRounds=5)"]
    Agent -- FINAL text --> Svc
    Svc -- TTS+sendChatMessage --> WS["Browser Bot (WS)"]
    WS -- audio/chat --> Meeting

    Audio["Meeting Audio"] --> STT["STT"]
    STT --> SpeechTeams["SPEECH_TEAMS (fast)"]
    SpeechTeams -- needsAgent? --> Agent
    SpeechTeams -- direct text/commands --> Svc
```

## Entscheidungen

| Datum      | Entscheidung                                    | Begruendung |
|------------|-------------------------------------------------|-------------|
| 2026-04-23 | Hybrid-Routing SPEECH_TEAMS + Agent             | Latenz fuer Reaktivitaet, Funktionalitaet fuer Komplexes |
| 2026-04-23 | Kein eigenes Teamsbot-Toolset im Agent          | Agent-Final-Text wird wie SPEECH_TEAMS-Text ausgeliefert; vermeidet Tool-Duplikation |
| 2026-04-23 | `web`-Toolbox als Default + `requestToolbox` aktiv | Recherche ist Standard, andere Toolboxen on-demand |
| 2026-04-23 | `maxRounds=5`, `maxCostCHF=0.10`                 | Live-Performance + Kosten-Cap |
| 2026-04-23 | UDB-Sidebar wie in CommcoachDossierView         | Bestehendes Muster, Files via fileIds |

## Umsetzungs-Checkliste

- [x] Datamodel `TeamsbotDirectorPrompt` + `SpeechTeamsResponse.needsAgent`
- [x] Interface CRUD + DB-Registrierung
- [x] `_activeServices` Registry + WS/Voice auf Instanz
- [x] `submitDirectorPrompt` + `_processDirectorPrompt` (Agent-Call + Delivery)
- [x] Persistente Prompts beim Reconnect aus DB laden
- [x] Hybrid: `_analyzeAndRespond` triggert Agent bei `needsAgent=true`
- [x] `_buildSpeechTeamsSystemPrompt` um `needsAgent`-Felder erweitern
- [x] Routes `POST/GET/DELETE /sessions/{id}/directorPrompts`
- [x] Frontend API + SSE-Event-Type
- [x] Frontend UDB-Sidebar + Regie-Panel + CSS
- [x] RBAC: nur Session-Owner darf submitten/listen/loeschen (`_validateInstanceAccess` + `_validateSessionOwnership`)
- [x] Neutralisierung: Director-Prompt-Text geht durch Standard-AiService -> automatisch im Scope
- [x] Navigation: keine neue Route, nur Panel in TeamsbotSessionView
- [x] Billing: laeuft ueber `agentService.runAgent` (Standard-Billing) und `aiService.callAi` (SPEECH_TEAMS Billing); kein neuer Pfad
- [x] Unit-Tests (26 Tests, T5 + AC 5 + AC 6 abgedeckt)
- [x] b-reference + TOPICS.md aktualisiert

## Akzeptanzkriterien

| # | Kriterium (Given-When-Then) | Prio |
|---|-----------------------------|------|
| 1 | Given laufendes Meeting, When Operator sendet One-Shot Prompt "Was ist die Hauptstadt von Frankreich?", Then Bot antwortet im Meeting per Voice "Paris" innerhalb 10s | must |
| 2 | Given laufendes Meeting + UDB-File ausgewaehlt, When Operator sendet Prompt "Fasse das ausgewaehlte Dokument zusammen", Then Bot liest Datei via `readFile`, fasst zusammen, antwortet Voice+Chat | must |
| 3 | Given laufendes Meeting, When Operator sendet Persistent-Prompt "Antworte immer in Englisch", Then jede folgende SPEECH_TEAMS-Antwort ist auf Englisch, bis Operator den Prompt loescht | must |
| 4 | Given Sprecher sagt "Nyla, recherchier was im Internet ueber SBB Schweiz", When SPEECH_TEAMS verarbeitet, Then `needsAgent=true` und Agent uebernimmt mit `webSearch`, antwortet ueber TTS | must |
| 5 | Given Operator sendet Prompt mit fileIds=[A,B,C], When Limit DIRECTOR_PROMPT_FILE_LIMIT (10) ueberschritten oder Text > 8000 Zeichen, Then Route gibt 400 zurueck | must |
| 6 | Given anderer User (nicht Owner) ruft GET /directorPrompts auf, Then 404 | must |

## Testplan

| ID | AC | Art | Automatisiert | Repo-Pfad | Status |
|----|----|-----|---------------|-----------|--------|
| T1 | 1  | manual e2e | nein | live meeting     | pending (manual) |
| T2 | 2  | manual e2e | nein | live meeting     | pending (manual) |
| T3 | 3  | manual e2e | nein | live meeting     | pending (manual) |
| T4 | 4  | manual e2e | nein | live meeting     | pending (manual) |
| T5 | 5,6| api unit   | ja | gateway/tests/unit/teamsbot/test_directorPrompts.py | done (26 Tests) |

## Links

- PR: TBD
- Issue: TBD

## Abschluss

- [x] `wiki/b-reference/teams-bot/architecture.md` (Director Prompts + Hybrid + Tool-Set)
- [x] `wiki/b-reference/gateway/ai-agent.md` (kein neues Teamsbot-Toolset, Hybrid-Routing)
- [x] `wiki/TOPICS.md` (Teams-Bot-Eintrag um Director Prompts ergaenzt + neuer Aktive-Arbeiten-Eintrag)
- [x] Diesen Plan nach `4-done/` verschieben