openmaic-custom/lib/buffer/stream-buffer.ts
wyuc ddb52241fb
feat: add Discussion TTS with per-agent voice assignment (#211)
* feat(tts): add resolveVoice() and getServerVoiceList() utilities

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tts): add AudioIndicator equalizer bars component

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tts): add onSegmentSealed callback to StreamBuffer

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tts): add voiceOverrides field to AgentConfig and AgentTemplate

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tts): add useDiscussionTTS hook with audio queue and cleanup

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): add audio state indicator to Roundtable bubble

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(tts): wire onSegmentSealed callback through chat sessions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): add per-agent voice dropdown to AgentBar

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): integrate useDiscussionTTS in Stage and pass state to Roundtable

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(tts): refine voice dropdown to pill-style selector

Replace native select styling with a compact rounded-full pill
that blends into the agent row. Remove border, use muted bg,
smaller text, and a custom chevron icon.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(tts): use shadcn Select for voice dropdown, link with TTS toggle

- Replace native <select> with shadcn Select component for consistent UI
- Hide voice dropdown when TTS is muted (ttsMuted)
- Compact pill-style trigger with rounded-full, no border, muted bg

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(tts): add voice label prefix and always show dropdown

Show "音色: Alloy" instead of plain "Alloy" in the voice pill.
Always show dropdown regardless of mute state (voice config is
independent of playback).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(tts): add volume icon hint in collapsed AgentBar

Show a small Volume2 icon in the collapsed pill when voice config
is available, hinting that voice settings are inside.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): fix voice dropdown layout and click handling

- Move voice pill below agent name (second line) to prevent
  horizontal overflow in English
- Wrap Select in div with onPointerDown stopPropagation to fix
  Radix click-through to parent row
- Add line-clamp-1 to descriptions for consistent row height
- Use items-start instead of items-center for better multi-line alignment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(tts): redesign AgentBar voice layout for compactness

- Single-line layout: checkbox · avatar · name · role · voice pill
- Remove descriptions from agent rows (saves vertical space)
- Extract AgentVoicePill component to isolate Select event handling
- Smaller avatars (size-7), tighter row padding (py-1.5)
- Voice pill uses Volume2 icon + voice name (no prefix text)
- Works in both Chinese and English without overflow

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): cross-provider voice selection per agent

- Change voiceConfig from per-provider lookup to explicit
  { providerId, voiceId } per agent
- Each agent can use a different TTS provider's voice
- Voice picker dropdown groups voices by provider
- useDiscussionTTS routes TTS requests per agent's provider
- resolveAgentVoice falls back to global provider if no config

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): align role badge and voice pill across agent rows

Give role badge fixed width (w-14 text-right) so role text
and voice pills align vertically across all rows regardless
of agent name length.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): fix role badge and voice pill alignment

Wrap role badge + voice pill in a fixed-width container
(w-[9.5rem] justify-end) so both align vertically across
all agent rows regardless of name or role text length.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style(tts): align role badge and voice pill across agent rows

Add min-w-[52px] text-right to role badge so it starts at a
consistent position regardless of agent name length.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): use fixed w-[60px] for role badge alignment

* fix(tts): use fixed w-[88px] for voice pill alignment

* fix(tts): prevent click-outside from closing AgentBar when Select portal is open

* fix(tts): comprehensive voice picker rewrite

- Replace Radix Select with Popover + button list (fixes click issue)
- Fix getAvailableProvidersWithVoices to always include global provider
- Widen panel from w-80 to w-96 (prevents name truncation)
- Voice pill uses primary color instead of gray (more visible)
- Extract renderAgentRow helper to reduce duplication
- Popover shows voices grouped by provider with active state
- Add findVoiceDisplayName utility

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): align voice provider availability with toolbar logic

* fix(tts): fallback to first available provider when global provider has no voices

* refactor(tts): remove global provider fallback from voice resolution

Voice resolution now only depends on available providers (those with
API keys or server-configured). No more globalProviderId parameter.
Fallback is first available provider, then browser-native-tts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): add browser native TTS voices to agent voice picker

Load speechSynthesis.getVoices() in AgentBar and include as a
"Browser Native" provider group in the voice popover. No API key
needed - always available if browser supports it.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): simplify toolbar TTS to on/off toggle, add disabled state

Toolbar:
- Replace volume slider with simple TTS on/off toggle button
- Remove ttsMuted/ttsVolume/onVolumeChange props from CanvasToolbar
- Toggle now controls ttsEnabled (not ttsMuted)

AgentBar:
- Collapsed: show VolumeX icon when TTS disabled
- Voice pills show disabled state (gray, cursor-not-allowed, no popover)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(tts): simplify Settings TTS tab to toggle + provider config

Remove voice selection, speed slider, preview/test, Azure locale
filter from Settings TTS tab. Voice is now per-agent in AgentBar.
Keep: on/off toggle, provider selector, API key + base URL config.
Add hint text pointing to AgentBar for voice configuration.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(tts): simplify media popover TTS tab to toggle only

* fix(tts): add voice config hint to media popover TTS tab

* feat(tts): add per-voice preview button in voice picker

Each voice row in the popover has a small speaker icon button.
Click to preview the voice with "欢迎来到AI课堂" / "Welcome to
AI Classroom" (follows i18n). Browser native uses Web Speech API,
server TTS calls /api/generate/tts. Click again or close popover
to stop. Shows spinner while generating.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): preview text follows course language instead of UI language

* refactor(tts): redesign AgentBar expanded panel layout

- Teacher always at top with voice pill (works in both modes)
- Mode tabs moved below teacher
- Auto mode: single compact row with shuffle icon + description
- Max turns: compact inline row with smaller input
- Preset mode: only student agents listed (teacher already above)
- Remove large shuffle animation from auto mode

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(tts): merge max turns into teacher row

* refactor(tts): separate teacher row and max turns, use stepper UI

- Teacher row: avatar + name + voice pill only
- Max turns: bottom row with MessageSquare icon + compact stepper
  (minus/number/plus in a rounded pill)
- Remove Input component dependency

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): increase voice pill contrast in dark mode

* fix(tts): make max turns input editable, tighten panel padding

* fix(tts): restore shuffle animation in auto mode (compact version)

* fix(tts): adjust auto mode text spacing and add voice auto-assign hint

* fix(tts): auto-close voice popover after selecting a voice

* fix(tts): increase auto mode vertical padding for better balance

* fix(tts): push auto mode text toward bottom with flex spacer

* fix(tts): reduce auto mode bottom padding

* feat(tts): wait for TTS audio to finish before next agent turn

Add waitForDrain() to useDiscussionTTS that returns a promise
resolving when the audio queue is empty. The agent loop in
useChatSessions now awaits this after buffer drain, so the next
agent's turn doesn't start until the current agent's TTS audio
finishes playing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): keep bubble visible while TTS audio is still playing

When buffer drains (text=null) but audio indicator is still active,
don't clear liveSpeech. Clear it only when audio state goes idle.
This keeps the speech bubble visible until TTS finishes.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): hold discussion bubble until TTS audio finishes

When StreamBuffer fires the done signal (onLiveSpeech null), Stage
now checks if TTS is still playing. If so, it defers clearing the
bubble state. The bubble stays visible until onAllAudioEnd fires
from the TTS hook (queue empty + nothing playing), then clears.

This prevents the jarring UX where the bubble disappears while
the agent's voice is still audible.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): fix bubble hold - guard onStopSession instead of onLiveSpeech

Root cause: bubble disappears because doSessionCleanup fires via
onStopSession when the agent loop ends naturally, NOT because of
onLiveSpeech(null, null).

Fix: when onStopSession fires and TTS is still playing, defer
doSessionCleanup to onAllAudioEnd callback. Manual stop (user
presses button) still cleans up immediately via handleStopDiscussion.

Use doSessionCleanupRef to avoid circular dependency between
discussionTTS hook and doSessionCleanup useCallback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): guard BOTH onLiveSpeech and onStopSession for bubble hold

Two paths clear the bubble:
1. onLiveSpeech(null, null) from StreamBuffer done → clears liveSpeech
2. onStopSession → doSessionCleanup → clears all state

Both fire when agent loop ends. Path 1 fires first (tick loop),
path 2 fires after (waitUntilDrained resolves). Both must be
guarded when TTS is still playing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): hold bubble during TTS playback and respect playback speed

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(tts): LLM picks voice matching agent persona during generation

- Client sends available voices (providerId + voiceId + name) to
  /api/generate/agent-profiles
- LLM prompt asks to pick a voice matching each agent's personality
- Parse "providerId::voiceId" from response, save as voiceConfig
- Fallback to index-based assignment if LLM doesn't pick
- Browser native voices hidden when server providers are available
- saveGeneratedAgents accepts and persists voiceConfig

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): restore volume slider in classroom toolbar

Revert the toolbar simplification from 36e3997 that replaced the
volume slider with a TTS on/off toggle. The volume control with
hover slider is a core classroom UX. TTS on/off is controlled via
Settings and Media popover instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): teacher uses global lecture voice in discussion when no voiceConfig override

* fix(tts): teacher always uses global lecture voice, no overrides

* fix(tts): sync playback speed to currently playing audio in real-time

* fix(tts): address code review issues

- Issue 2: enabled flag now checks ttsEnabled && !ttsMuted in stage.tsx
- Issue 4: remove unused browserAvailableVoices from useDiscussionTTS
- Issue 5: remove dead code in audio-settings.tsx (Slider, Loader2, handleTTSVoiceChange, handleTTSSpeedChange, handleTestTTS, testingTTS, ttsTestStatus, ttsTestMessage, testText, ttsSpeed, setTTSSpeed, and unused browser-tts-preview imports)
- Issue 6: shouldHold now checks queue length in addition to isPlayingRef
- Issue 8: hide AgentVoicePill for teacher row in agent-bar.tsx (teacher voice is controlled in Settings)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(tts): address PR review — abort preview fetch, defer error recovery

1. Add AbortController to voice preview server TTS fetch, abort on
   stopPreview to prevent stale responses on rapid switching
2. Use queueMicrotask for processQueue calls in error/ended handlers
   to prevent synchronous recursion if multiple items fail consecutively
3. Add ordering invariant comment on sealLastText's onSegmentSealed

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(tts): restore teacher voice pill, respect voiceConfig override

* fix(tts): sync volume and mute to discussion TTS audio in real-time

* fix(tts): allow browser-native TTS alongside server providers

* fix(tts): remove top padding from voice popover content

* fix(tts): make selectedAgents reactive to voiceConfig changes

* fix(tts): use agents record instead of listAgents() to avoid infinite loop

* fix(tts): single source of truth for teacher voice

Teacher voice pill now reads/writes global ttsProviderId + ttsVoice
(same settings used by lecture TTS). This ensures lecture and
discussion always use the same teacher voice. Student agents still
use per-agent voiceConfig.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add avatar descriptions for smarter LLM avatar selection

Each avatar now has a one-line description (appearance, vibe) sent
to the agent-profiles generation API. LLM picks avatars matching
agent personality instead of guessing from file paths.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: 杨慎 <117187635+cosarah@users.noreply.github.com>
2026-03-23 17:35:09 +08:00

647 lines
21 KiB
TypeScript

import type { DirectorState } from '@/lib/types/chat';
/**
* StreamBuffer — unified presentation pacing layer.
*
* Sits between data sources (SSE stream / PlaybackEngine) and React state.
* Events are pushed into an ordered queue; a fixed-rate tick loop reveals
* text character-by-character and fires typed callbacks so both the Chat
* area and the Roundtable bubble consume identically-paced content.
*
* Key invariants:
* - ONE source of pacing (this tick loop) — no double typewriter.
* - pause() is O(1) instant — tick returns immediately.
* - Actions fire only when the tick cursor reaches them (after preceding text).
* - Roundtable sees only the current speech segment (resets on action / agent switch).
*/
// ─── Buffer Item Types ───────────────────────────────────────────────
export interface AgentStartItem {
kind: 'agent_start';
messageId: string;
agentId: string;
agentName: string;
avatar?: string;
color?: string;
}
export interface AgentEndItem {
kind: 'agent_end';
messageId: string;
agentId: string;
}
export interface TextItem {
kind: 'text';
messageId: string;
agentId: string;
/** Unique ID for this text part — distinguishes multiple text items within one message (e.g. lecture). */
partId: string;
/** Growable — SSE deltas append here. */
text: string;
/** When true, no more text will be appended. Tick can advance past once fully revealed. */
sealed: boolean;
}
export interface ActionItem {
kind: 'action';
messageId: string;
actionId: string;
actionName: string;
params: Record<string, unknown>;
agentId: string;
}
export interface ThinkingItem {
kind: 'thinking';
stage: string;
agentId?: string;
}
export interface CueUserItem {
kind: 'cue_user';
fromAgentId?: string;
prompt?: string;
}
export interface DoneItem {
kind: 'done';
totalActions: number;
totalAgents: number;
agentHadContent?: boolean;
directorState?: DirectorState;
}
export interface ErrorItem {
kind: 'error';
message: string;
}
export type BufferItem =
| AgentStartItem
| AgentEndItem
| TextItem
| ActionItem
| ThinkingItem
| CueUserItem
| DoneItem
| ErrorItem;
// ─── Callbacks ───────────────────────────────────────────────────────
export interface StreamBufferCallbacks {
onAgentStart(data: AgentStartItem): void;
onAgentEnd(data: AgentEndItem): void;
/**
* Fired each tick while a text item is being revealed.
* @param messageId — which message to update
* @param partId — unique ID for this text part (stable across ticks)
* @param revealedText — text visible so far (slice of full text)
* @param isComplete — true when this text item is fully revealed AND sealed
*/
onTextReveal(messageId: string, partId: string, revealedText: string, isComplete: boolean): void;
/** Fired when tick reaches an action item. Callers should execute the effect + add badge. */
onActionReady(messageId: string, data: ActionItem): void;
/**
* Unified speech feed for the Roundtable bubble.
* Reports only the CURRENT segment text (resets on action / agent switch).
* Called with (null, null) when buffer completes or is disposed.
*/
onLiveSpeech(text: string | null, agentId: string | null): void;
/**
* Speech progress ratio for the Roundtable bubble auto-scroll.
* Fired each tick during text reveal: ratio = charCursor / totalTextLength.
* Called with null when buffer completes or is disposed.
*/
onSpeechProgress(ratio: number | null): void;
onThinking(data: { stage: string; agentId?: string } | null): void;
onCueUser(fromAgentId?: string, prompt?: string): void;
onDone(data: {
totalActions: number;
totalAgents: number;
agentHadContent?: boolean;
directorState?: DirectorState;
}): void;
onError(message: string): void;
onSegmentSealed?: (
messageId: string,
partId: string,
fullText: string,
agentId: string | null,
) => void;
/**
* When provided, called after a text item is fully revealed and sealed.
* If it returns true, the tick loop will NOT advance to the next item —
* the bubble stays on the current text (e.g. waiting for TTS playback to finish).
*/
shouldHoldAfterReveal?: () => boolean;
}
// ─── Options ─────────────────────────────────────────────────────────
export interface StreamBufferOptions {
/** Milliseconds between ticks. Default: 30 */
tickMs?: number;
/** Characters revealed per tick. Default: 1 (≈33 chars/s) */
charsPerTick?: number;
/**
* Fixed delay (ms) after a text segment is fully revealed before advancing
* to the next item. Gives the reader a breathing pause after each speech
* block. Default: 0 (no delay).
*/
postTextDelayMs?: number;
/**
* Delay (ms) after firing an action callback before advancing to the next
* item. Gives action animations time to play out. Default: 0.
*/
actionDelayMs?: number;
}
// ─── StreamBuffer Class ──────────────────────────────────────────────
export class StreamBuffer {
// Queue
private items: BufferItem[] = [];
private readIndex = 0;
private charCursor = 0;
// Roundtable segment tracking
private currentSegmentText = '';
private currentAgentId: string | null = null;
// Control
private _paused = false;
private _disposed = false;
private timer: ReturnType<typeof setInterval> | null = null;
// Dwell / delay counters (in ticks)
private _dwellTicksRemaining = 0;
/** True when a text item's post-delay has elapsed and we're waiting for TTS to finish. */
private _holdingForTTS = false;
// Config
private readonly tickMs: number;
private readonly charsPerTick: number;
private readonly postTextDelayTicks: number;
private readonly actionDelayTicks: number;
private readonly cb: StreamBufferCallbacks;
private partCounter = 0;
private _drainResolve: (() => void) | null = null;
private _drainReject: ((err: Error) => void) | null = null;
constructor(callbacks: StreamBufferCallbacks, options?: StreamBufferOptions) {
this.cb = callbacks;
this.tickMs = options?.tickMs ?? 30;
this.charsPerTick = options?.charsPerTick ?? 1;
this.postTextDelayTicks = Math.ceil((options?.postTextDelayMs ?? 0) / this.tickMs);
this.actionDelayTicks = Math.ceil((options?.actionDelayMs ?? 0) / this.tickMs);
}
// ─── Push Methods ────────────────────────────────────────────────
pushAgentStart(data: Omit<AgentStartItem, 'kind'>): void {
if (this._disposed) return;
this.sealLastText();
this.items.push({ kind: 'agent_start', ...data });
}
pushAgentEnd(data: Omit<AgentEndItem, 'kind'>): void {
if (this._disposed) return;
this.sealLastText();
this.items.push({ kind: 'agent_end', ...data });
}
/**
* Append text for a message.
* If the last queue item is an unsealed text item for the same messageId,
* the delta is appended in-place. Otherwise a new text item is created.
*/
pushText(messageId: string, delta: string, agentId?: string): void {
if (this._disposed) return;
const last = this.items[this.items.length - 1];
if (last && last.kind === 'text' && last.messageId === messageId && !last.sealed) {
last.text += delta;
} else {
this.items.push({
kind: 'text',
messageId,
agentId: agentId ?? this.currentAgentId ?? '',
partId: `p${this.partCounter++}`,
text: delta,
sealed: false,
});
}
}
/** Mark the current (last) text item as complete — no more appends expected. */
sealText(messageId: string): void {
if (this._disposed) return;
for (let i = this.items.length - 1; i >= 0; i--) {
const item = this.items[i];
if (item.kind === 'text' && item.messageId === messageId && !item.sealed) {
item.sealed = true;
break;
}
}
}
pushAction(data: Omit<ActionItem, 'kind'>): void {
if (this._disposed) return;
this.sealLastText();
this.items.push({ kind: 'action', ...data });
}
pushThinking(data: { stage: string; agentId?: string }): void {
if (this._disposed) return;
this.items.push({ kind: 'thinking', ...data });
}
pushCueUser(data: { fromAgentId?: string; prompt?: string }): void {
if (this._disposed) return;
this.items.push({ kind: 'cue_user', ...data });
}
pushDone(data: {
totalActions: number;
totalAgents: number;
agentHadContent?: boolean;
directorState?: DirectorState;
}): void {
if (this._disposed) return;
this.sealLastText();
this.items.push({ kind: 'done', ...data });
}
pushError(message: string): void {
if (this._disposed) return;
this.items.push({ kind: 'error', message });
}
// ─── Control ─────────────────────────────────────────────────────
/** Start the tick loop. Idempotent — calling twice is safe. */
start(): void {
if (this._disposed || this.timer) return;
this.timer = setInterval(() => this.tick(), this.tickMs);
}
/** Instantly pause — tick becomes a no-op. */
pause(): void {
this._paused = true;
}
/** Resume from exactly where we left off. */
resume(): void {
this._paused = false;
}
/**
* Returns a Promise that resolves when the buffer has processed all items
* including the final `done` item. Rejects if the buffer is disposed/shutdown
* before draining completes.
*/
waitUntilDrained(): Promise<void> {
if (this._disposed) {
return Promise.reject(new Error('Buffer already disposed'));
}
return new Promise<void>((resolve, reject) => {
this._drainResolve = resolve;
this._drainReject = reject;
});
}
get paused(): boolean {
return this._paused;
}
get disposed(): boolean {
return this._disposed;
}
/**
* Flush: instantly reveal everything remaining.
* Used when restoring persisted sessions or force-completing.
*/
flush(): void {
if (this._disposed) return;
while (this.readIndex < this.items.length) {
const item = this.items[this.readIndex];
switch (item.kind) {
case 'text':
this.cb.onTextReveal(item.messageId, item.partId, item.text, true);
this.currentSegmentText = item.text;
this.cb.onLiveSpeech(this.currentSegmentText, this.currentAgentId);
this.cb.onSpeechProgress(1);
break;
case 'action':
this.currentSegmentText = '';
this.cb.onActionReady(item.messageId, item);
this.cb.onLiveSpeech(null, this.currentAgentId);
break;
case 'agent_start':
this.currentAgentId = item.agentId;
this.currentSegmentText = '';
this.cb.onThinking(null); // Agent selected — clear thinking indicator
this.cb.onAgentStart(item);
this.cb.onLiveSpeech(null, item.agentId);
break;
case 'agent_end':
this.cb.onAgentEnd(item);
break;
case 'thinking':
this.cb.onThinking(item);
break;
case 'cue_user':
this.cb.onCueUser(item.fromAgentId, item.prompt);
break;
case 'done':
this.cb.onLiveSpeech(null, null);
this.cb.onSpeechProgress(null);
this.cb.onThinking(null);
this.cb.onDone(item);
// Resolve drain promise
this._drainResolve?.();
this._drainResolve = null;
this._drainReject = null;
break;
case 'error':
this.cb.onError(item.message);
break;
}
this.readIndex++;
this.charCursor = 0;
}
}
/** Stop tick loop, release resources. No more callbacks after this. */
dispose(): void {
if (this._disposed) return;
this._disposed = true;
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
// Reject waiting drain promise
this._drainReject?.(new Error('Buffer disposed'));
this._drainResolve = null;
this._drainReject = null;
// Final cleanup signal
this.cb.onLiveSpeech(null, null);
this.cb.onSpeechProgress(null);
}
/**
* Stop the tick timer and mark disposed WITHOUT firing final onLiveSpeech.
* Used when replacing a buffer (e.g. resume after soft-pause) to avoid
* the dispose callback clearing roundtable state via a stale microtask.
*/
shutdown(): void {
if (this._disposed) return;
this._disposed = true;
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
// Reject waiting drain promise
this._drainReject?.(new Error('Buffer shutdown'));
this._drainResolve = null;
this._drainReject = null;
}
// ─── Internals ───────────────────────────────────────────────────
/** Seal the last text item in the queue (if any). */
private sealLastText(): void {
for (let i = this.items.length - 1; i >= 0; i--) {
const item = this.items[i];
if (item.kind === 'text' && !item.sealed) {
item.sealed = true;
// Ordering invariant: sealLastText() is called BEFORE pushAgentEnd/pushAgentStart,
// so this.currentAgentId still refers to the agent whose text is being sealed.
this.cb.onSegmentSealed?.(item.messageId, item.partId, item.text, this.currentAgentId);
break;
}
// Stop searching once we hit a non-text item
if (item.kind !== 'text') break;
}
}
private tick(): void {
if (this._paused || this._disposed) return;
// Honour dwell / action-delay countdown before advancing
if (this._dwellTicksRemaining > 0) {
this._dwellTicksRemaining--;
if (this._dwellTicksRemaining === 0 && this._holdingForTTS) {
// Post-text delay just finished — fall through to the TTS hold check below
} else {
return;
}
}
// TTS hold: after post-text delay, keep the bubble on screen while audio plays
if (this._holdingForTTS) {
if (this.cb.shouldHoldAfterReveal?.()) {
return; // TTS still playing — stay on current item
}
this._holdingForTTS = false;
// TTS done — continue to process next item
this.advanceNonText();
return;
}
const item = this.items[this.readIndex];
if (!item) return; // Queue empty or caught up — wait
switch (item.kind) {
case 'text': {
// Advance character cursor
this.charCursor = Math.min(this.charCursor + this.charsPerTick, item.text.length);
const revealed = item.text.slice(0, this.charCursor);
const fullyRevealed = this.charCursor >= item.text.length;
const isComplete = fullyRevealed && item.sealed;
// Update chat area
this.cb.onTextReveal(item.messageId, item.partId, revealed, isComplete);
// Update roundtable (current segment only).
// Use this.currentAgentId (set when tick processes agent_start) rather than
// item.agentId — push-time race means item.agentId can carry a stale value
// from the previous agent when SSE pushes outpace the tick loop.
this.currentSegmentText = revealed;
this.cb.onLiveSpeech(this.currentSegmentText, this.currentAgentId);
this.cb.onSpeechProgress(item.text.length > 0 ? this.charCursor / item.text.length : 1);
// Advance to next item if fully revealed and sealed
if (isComplete) {
this.readIndex++;
this.charCursor = 0;
// Fixed pause after text finishes — gives the reader a breathing gap
// before the next action or agent turn fires.
if (this.postTextDelayTicks > 0) {
this._dwellTicksRemaining = this.postTextDelayTicks;
// If TTS hold callback exists, mark that we need to check it after delay
if (this.cb.shouldHoldAfterReveal) {
this._holdingForTTS = true;
}
return; // next tick will count down, then advanceNonText
}
// No post-text delay — check TTS hold immediately
if (this.cb.shouldHoldAfterReveal?.()) {
this._holdingForTTS = true;
return; // TTS still playing — hold here
}
// Process any immediately-advanceable items in the same tick
// (e.g. action badges right after text)
this.advanceNonText();
}
// If fullyRevealed but !sealed: wait for more SSE deltas
break;
}
// Non-text items are processed immediately
case 'agent_start':
this.currentAgentId = item.agentId;
this.currentSegmentText = '';
this.cb.onThinking(null); // Agent selected — clear thinking indicator
this.cb.onAgentStart(item);
this.cb.onLiveSpeech(null, item.agentId);
this.readIndex++;
this.charCursor = 0;
this.advanceNonText();
break;
case 'agent_end':
this.cb.onAgentEnd(item);
this.readIndex++;
this.charCursor = 0;
this.advanceNonText();
break;
case 'action':
this.currentSegmentText = '';
this.cb.onActionReady(item.messageId, item);
this.cb.onLiveSpeech(null, this.currentAgentId);
this.readIndex++;
this.charCursor = 0;
// Delay after action so animations have time to play out
if (this.actionDelayTicks > 0) {
this._dwellTicksRemaining = this.actionDelayTicks;
return;
}
this.advanceNonText();
break;
case 'thinking':
this.cb.onThinking(item);
this.readIndex++;
this.charCursor = 0;
this.advanceNonText();
break;
case 'cue_user':
this.cb.onCueUser(item.fromAgentId, item.prompt);
this.readIndex++;
this.charCursor = 0;
this.advanceNonText();
break;
case 'done':
this.cb.onLiveSpeech(null, null);
this.cb.onSpeechProgress(null);
this.cb.onThinking(null);
this.cb.onDone(item);
this.readIndex++;
this.charCursor = 0;
// Stop the timer — nothing more to process
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
// Resolve drain promise
this._drainResolve?.();
this._drainResolve = null;
this._drainReject = null;
break;
case 'error':
this.cb.onError(item.message);
this.readIndex++;
this.charCursor = 0;
this.advanceNonText();
break;
}
}
/**
* After processing a non-text item, keep advancing through consecutive
* non-text items in the same tick. Stop when we hit a text item or
* the end of the queue — the next tick will handle the text item
* (so we don't skip the character-by-character reveal).
*
* Also stops when an action triggers a delay so its animation can play.
*/
private advanceNonText(): void {
while (this.readIndex < this.items.length) {
const next = this.items[this.readIndex];
if (next.kind === 'text') break; // Let the next tick handle text
switch (next.kind) {
case 'agent_start':
this.currentAgentId = next.agentId;
this.currentSegmentText = '';
this.cb.onThinking(null); // Agent selected — clear thinking indicator
this.cb.onAgentStart(next);
this.cb.onLiveSpeech(null, next.agentId);
break;
case 'agent_end':
this.cb.onAgentEnd(next);
break;
case 'action':
this.currentSegmentText = '';
this.cb.onActionReady(next.messageId, next);
this.cb.onLiveSpeech(null, this.currentAgentId);
this.readIndex++;
this.charCursor = 0;
// Pause after action to let animation play
if (this.actionDelayTicks > 0) {
this._dwellTicksRemaining = this.actionDelayTicks;
return; // resume on next tick after countdown
}
continue; // no delay — keep advancing
case 'thinking':
this.cb.onThinking(next);
break;
case 'cue_user':
this.cb.onCueUser(next.fromAgentId, next.prompt);
break;
case 'done':
this.cb.onLiveSpeech(null, null);
this.cb.onSpeechProgress(null);
this.cb.onThinking(null);
this.cb.onDone(next);
this.readIndex++;
this.charCursor = 0;
if (this.timer) {
clearInterval(this.timer);
this.timer = null;
}
// Resolve drain promise
this._drainResolve?.();
this._drainResolve = null;
this._drainReject = null;
return; // done — stop advancing
case 'error':
this.cb.onError(next.message);
break;
}
this.readIndex++;
this.charCursor = 0;
}
}
}