Files
CyberGril/web/src/voice/session.ts
T

426 lines
28 KiB
TypeScript

// ── Continuous voice on the approved conversation (R5, HEL-878). ──
// The server opens a room and hands out a short join token (POST /api/voice/session, keys never reach the page); the
// browser joins with the existing LiveKit client and publishes the microphone. Her words are spoken by the dedicated
// worker, which goes through the same /api/chat as text; the page never confirms a receipt for voice (the worker does,
// only after real playout) and never turns subtitles into chat rows: the record is re-read from /api/messages.
//
// One rule holds the whole lifecycle together: every call starts a new generation, and anything that answers for an
// older generation (a late token, a late join, a late microphone, a late room event) is cleaned up, never shown.
import type { Message } from '../domain/model';
import type { ShownMessage } from '../chat/reading';
import { api, toMessage, within, type MessagePage } from '../adapters/real';
import { serverId } from '../adapters/inbox';
export type VoicePhase = 'off' | 'opening' | 'joining' | 'listening' | 'thinking' | 'speaking';
export interface VoiceView {
phase: VoicePhase;
// What the recogniser heard of you so far (a draft; it is replaced, never stored).
heard: string;
// Her line spoken after a failure (φ): heard, not part of the record.
spoken: string;
// What she is saying right now, shown on the stage where her text replies appear; never stored by the page.
her: HerLine | null;
// Why voice is off or what went wrong; empty while it simply runs.
notice: string;
// The browser held her audio back until a tap (autoplay rules); `resume` lets it out.
blocked: boolean;
// The voice the server pinned for THIS call (HEL-903, session response `voice`): null until a room is granted;
// `id: null` when the server did not say. It stays for the whole call; a choice made in settings is the next call's.
voice: CallVoice | null;
}
export interface CallVoice { id: string | null }
// One "she speaks" (an SDK speech): her reply to your voice turn, or a stored reach-out read aloud. `open` grows by
// replacement (each interim is the whole text so far); `final` is the stored reply's exact text; `done` is closed and
// stays only until the record (or the next turn) takes its place.
export interface HerLine { speech: string; text: string; state: 'open' | 'final' | 'done'; turnId?: string; messageId?: number; proactive?: boolean }
export const OFF: VoiceView = { phase: 'off', heard: '', spoken: '', her: null, notice: '', blocked: false, voice: null };
// ── cg.subtitle contract v2 (docs/voice-subtitle-contract-v2.md). Anything that is not exactly v2 is dropped. ──
const USER_KINDS = ['interim', 'user_final'] as const;
const HER_KINDS = ['turn_start', 'assistant_interim', 'assistant_final', 'turn_end', 'turn_cancel', 'error', 'proactive_start', 'proactive_end', 'proactive_cancel'] as const;
export type SubtitleKind = typeof USER_KINDS[number] | typeof HER_KINDS[number];
export interface Subtitle { seq: number; kind: SubtitleKind; role: 'user' | 'assistant'; text: string; speech: string; turnId?: string; messageId?: number; reason?: string }
const id = (v: unknown) => typeof v === 'string' && v.length > 0 && v.length <= 200 ? v : '';
export function subtitle(v: unknown): Subtitle | null {
const s = v as Record<string, unknown> | null;
if (!s || typeof s !== 'object' || Array.isArray(s) || s.v !== 2 || !Number.isSafeInteger(s.seq) || (s.seq as number) <= 0 || typeof s.text !== 'string') return null;
const kind = s.kind as SubtitleKind, user = (USER_KINDS as readonly string[]).includes(kind);
if (!user && !(HER_KINDS as readonly string[]).includes(kind)) return null;
if (s.role !== (user ? 'user' : 'assistant')) return null;
const out: Subtitle = { seq: s.seq as number, kind, role: user ? 'user' : 'assistant', text: s.text, speech: user ? '' : id(s.speech_id) };
if (!user && !out.speech) return null;
if (s.turn_id !== undefined && s.turn_id !== null) { if (!id(s.turn_id)) return null; out.turnId = s.turn_id as string; }
if (kind === 'assistant_final' && !out.turnId) return null;
if (kind.startsWith('proactive_')) { if (!Number.isSafeInteger(s.message_id) || (s.message_id as number) <= 0) return null; out.messageId = s.message_id as number; }
if (typeof s.reason === 'string') out.reason = s.reason;
return out;
}
// ── What the controller needs from a real-time client. livekit.ts implements it with livekit-client; tests use fakes. ──
export interface MicTrack { stop(): void; onEnded(cb: () => void): void }
export interface RoomEvents {
agentJoined(): void;
// Her worker left the room while it stays open (its job ended or crashed): nobody is answering any more.
agentLeft(): void;
// The worker's own state attribute (lk.agent.state): initializing / listening / thinking / speaking.
agentState(state: string): void;
subtitle(payload: unknown): void;
// The room went away without us closing it (server ended it, network, kicked).
dropped(): void;
audioBlocked(blocked: boolean): void;
}
export interface VoiceRoom { publish(mic: MicTrack): Promise<void>; hush(on: boolean): void; resumeAudio(): Promise<void>; close(): Promise<void> }
export interface VoiceTransport { capture(): Promise<MicTrack>; join(url: string, token: string, on: RoomEvents, signal: AbortSignal): Promise<VoiceRoom> }
export interface VoiceAvailability { available: boolean; reason: string }
export interface SessionGrant { url: string; token: string; room: string; session_id: string; epoch: number; expires_at: number; voice?: unknown }
// Only an id the voice list could hold is taken as the call's voice; anything else is "not said", never guessed.
export const callVoiceOf = (grant: { voice?: unknown }): CallVoice => ({ id: typeof grant.voice === 'string' && /^[\w-]{1,40}$/u.test(grant.voice) ? grant.voice : null });
export const WORDS = {
notConfigured: '语音还没有在这台服务上配置,文字仍可使用。',
ttsDown: '她的声音服务这会儿不在,稍后再试试。文字仍可使用。',
noRoute: '这台服务还没有语音通路,文字仍可使用。',
unknown: '暂时读不到语音状态,文字仍可使用。',
insecure: '这个地址不是安全连接,浏览器不允许使用麦克风。需要从 HTTPS 入口打开。',
denied: '没有拿到麦克风权限,语音没有开始。文字仍可使用。',
noMic: '没有找到可用的麦克风,语音没有开始。',
micBusy: '麦克风被别的程序占用了,语音没有开始。',
client: '语音组件没有加载出来,文字仍可使用。',
unreachable: '通话服务暂时连不上,稍后再试试。',
noAgent: '她没有接上这次通话,麦克风已经关闭。文字仍可使用。',
agentLeft: '她那边的语音中断了,这次通话已结束,麦克风已经关闭。文字仍可使用。',
dropped: '通话断开了,麦克风已经关闭。文字仍可使用。',
micGone: '麦克风被关掉了,语音已结束。',
offline: '网络断开了,语音已结束,麦克风已关闭。',
} as const;
export interface VoiceDeps {
transport: () => Promise<VoiceTransport>;
onView: (view: VoiceView) => void;
// The record may have changed (a voice turn began, ended or was cut): re-read /api/messages.
onRecord: () => void;
// You finished saying something by voice: a text reply still streaming has been cancelled by the server.
onSpoke: () => void;
fetch?: typeof fetch;
// How long the room may wait for her worker to join before giving up honestly.
agentWaitMs?: number;
secure?: () => boolean;
}
// seq: the highest subtitle sequence applied in this call (one worker job, one sequence). speech: her speech open now;
// closed: speeches that ended, were cancelled or were superseded in this call; nothing for them is shown again. It is
// kept for the whole call (no window a long call could push a retired speech out of) and goes with the call.
interface Live { gen: number; abort: AbortController; mic?: MicTrack; room?: VoiceRoom; session?: string; agent: boolean; stated: boolean; hushed: boolean; timer?: ReturnType<typeof setTimeout>; seq: number; speech: string; pro: boolean; message?: number; closed: Set<string> }
const AGENT_PHASE: Record<string, VoicePhase> = { initializing: 'joining', listening: 'listening', thinking: 'thinking', speaking: 'speaking' };
// What GET /api/voice/status can actually tell (HEL-903): no route on this server, not configured, configured with the
// TTS health probe passing ('ok') or failing ('down'), or unreadable. It says nothing about recognition on its own and
// never that a whole call works end to end (`voice` stays false until real-device acceptance).
export type VoiceStatusKind = 'none' | 'off' | 'ok' | 'down' | 'unknown';
export async function readVoiceStatus(signal: AbortSignal, f: typeof fetch = fetch): Promise<VoiceStatusKind> {
let response: Response;
try { response = await f('/api/voice/status', { signal }); } catch (e) { if (signal.aborted) throw e; return 'unknown'; }
// A server from before R5 has no such route: that is "not wired", not a failure.
if (response.status === 404 || response.status === 405) return 'none';
const data = await response.json().catch(() => null) as { configured?: unknown; tts_ok?: unknown } | null;
if (!response.ok || !data) return 'unknown';
if (data.configured !== true) return 'off';
return data.tts_ok === true ? 'ok' : 'down';
}
const REASON: Record<VoiceStatusKind, string> = { none: WORDS.noRoute, off: WORDS.notConfigured, ok: '', down: WORDS.ttsDown, unknown: WORDS.unknown };
export async function voiceStatus(signal: AbortSignal, f: typeof fetch = fetch): Promise<VoiceAvailability> {
const kind = await readVoiceStatus(signal, f);
return { available: kind === 'ok', reason: REASON[kind] };
}
function micFailure(e: unknown, secure: boolean) {
const name = (e as { name?: string } | null)?.name || '';
if (!secure) return WORDS.insecure;
if (name === 'NotAllowedError' || name === 'SecurityError' || name === 'PermissionDeniedError') return WORDS.denied;
if (name === 'NotFoundError' || name === 'DevicesNotFoundError' || name === 'OverconstrainedError') return WORDS.noMic;
if (name === 'NotReadableError' || name === 'AbortError') return WORDS.micBusy;
return WORDS.denied;
}
const OWED = 'cg.voice.owed';
function owedSessions(): string[] {
try { const v = JSON.parse(localStorage.getItem(OWED) || '[]'); return Array.isArray(v) ? v.filter((s): s is string => typeof s === 'string' && !!s && s.length < 100) : []; } catch { return []; }
}
export class VoiceController {
private gen = 0;
private live: Live | null = null;
private view: VoiceView = OFF;
private f: typeof fetch;
constructor(private deps: VoiceDeps) { this.f = deps.fetch ?? ((...a) => fetch(...a)); }
get phase() { return this.view.phase; }
get active() { return this.live !== null; }
private show(next: Partial<VoiceView>, gen: number) {
if (gen !== this.gen) return;
this.view = { ...this.view, ...next };
this.deps.onView(this.view);
}
async start(): Promise<void> {
// The generation is taken before anything is awaited, so a start that wakes up after a newer one never takes
// the call over; the call it replaces is released first, as end() would.
const prev = this.live;
const gen = ++this.gen, live: Live = { gen, abort: new AbortController(), agent: false, stated: false, hushed: false, seq: 0, speech: '', pro: false, closed: new Set() };
this.live = live;
this.view = { ...OFF, phase: 'opening' }; this.deps.onView(this.view);
const stale = () => gen !== this.gen;
if (prev) { await this.teardown(prev); this.deps.onRecord(); }
if (stale()) return;
void this.settle();
// Everything a failure says is said while this call still owns the page; its cleanup goes on afterwards and,
// however late it answers, only releases this call's own microphone, room and server room.
const fail = (notice: string) => {
if (stale()) return Promise.resolve();
this.live = null; this.gen++;
const released = this.teardown(live);
this.view = { ...OFF, notice }; this.deps.onView(this.view);
return released;
};
const secure = (this.deps.secure ?? (() => window.isSecureContext && !!navigator.mediaDevices?.getUserMedia))();
if (!secure) return fail(WORDS.insecure);
// 1. The honest switch: configured and her voice service reachable (no room, no microphone yet).
let status: VoiceAvailability;
try { status = await voiceStatus(live.abort.signal, this.f); } catch { return; }
if (stale()) return;
if (!status.available) return fail(status.reason);
// 2. The client, then the microphone. A refusal here opens nothing on the server.
let transport: VoiceTransport;
try { transport = await this.deps.transport(); } catch { return fail(WORDS.client); }
if (stale()) return;
let mic: MicTrack;
try { mic = await transport.capture(); } catch (e) { return fail(micFailure(e, true)); }
if (stale()) { mic.stop(); return; }
live.mic = mic;
mic.onEnded(() => { if (!stale()) void fail(WORDS.micGone); });
// 3. A room of her own for this call. This request is not cut short by ending: if it was already under way, its
// answer still owns a room on the server, so it is waited for and given back.
let response: Response, data: (SessionGrant & { detail?: unknown }) | null;
try {
response = await this.f('/api/voice/session', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}', signal: AbortSignal.timeout(15000) });
data = await response.json().catch(() => null);
} catch { return fail(WORDS.unreachable); }
if (response.ok && typeof data?.session_id === 'string') live.session = data.session_id;
if (stale()) { await this.teardown(live); return; }
if (!response.ok || !data?.token || !data.url || !live.session) return fail(typeof data?.detail === 'string' && data.detail ? data.detail : WORDS.unreachable);
const grant = data;
// 4. Join and speak. The voice this room was opened with is shown from here to the end of this call; a late grant
// of an older call never gets here (stale), and every end or failure resets the view.
this.show({ phase: 'joining', voice: callVoiceOf(grant) }, gen);
const events: RoomEvents = {
agentJoined: () => { if (stale() || live.agent) return; live.agent = true; clearTimeout(live.timer); if (!live.stated) this.show({ phase: 'listening' }, gen); },
// Her worker gone with the room still open: no one would ever answer, so the call ends honestly, exactly as a
// failure does (her line, microphone, her audio, room and server room all go; an unsent DELETE is owed).
agentLeft: () => { if (!stale() && live.agent) void fail(WORDS.agentLeft); },
agentState: state => {
if (stale()) return;
const phase = AGENT_PHASE[state]; if (!phase) return;
live.stated = true;
if (phase !== 'joining' && !live.agent) events.agentJoined();
// After text took over, her old voice stays silent until she is back to listening.
if (live.hushed && phase !== 'speaking') { live.hushed = false; live.room?.hush(false); }
this.show({ phase, ...(phase === 'thinking' ? { spoken: '' } : {}) }, gen);
},
subtitle: payload => {
if (stale()) return;
// Replays, late frames of an older turn and frames that overtook each other all sit at or below the
// highest sequence already applied in this call.
const s = subtitle(payload); if (!s || s.seq <= live.seq) return;
live.seq = s.seq;
this.hear(live, s);
},
dropped: () => { if (!stale()) void fail(WORDS.dropped); },
audioBlocked: blocked => this.show({ blocked }, gen),
};
let room: VoiceRoom;
try { room = await transport.join(grant.url, grant.token, events, live.abort.signal); } catch { return fail(WORDS.unreachable); }
if (stale()) { live.room = room; await this.teardown(live); return; }
live.room = room;
try { await room.publish(mic); } catch { return fail(WORDS.unreachable); }
if (stale()) { await this.teardown(live); return; }
if (!live.agent) live.timer = setTimeout(() => { if (!stale() && !live.agent) void fail(WORDS.noAgent); }, this.deps.agentWaitMs ?? 20000);
}
// Stop everything now: microphone first, then the room and its audio, then the server-side room. Safe to call twice.
async end(notice = ''): Promise<void> {
const live = this.live;
this.gen++; this.live = null;
const was = this.view.phase !== 'off' || this.view.notice !== notice;
this.view = { ...OFF, notice };
if (was) this.deps.onView(this.view);
if (live) { await this.teardown(live); this.deps.onRecord(); }
}
// Page is going away: same order, without waiting; the DELETE survives the unload.
unload() {
const live = this.live;
this.gen++; this.live = null; this.view = OFF;
if (live) void this.teardown(live, true);
}
// One subtitle that passed the sequence gate. Your draft and her line never share a slot: `heard` is yours, `her`
// is hers. Her frames act only on the speech open now; a speech once closed here is never shown again.
private hear(live: Live, s: Subtitle) {
const gen = live.gen, cur = this.view.her, honest = (phase: VoicePhase) => live.stated ? {} : { phase };
if (s.kind === 'interim') {
// Your draft. Her open line is left to the server's cancel (an SDK barge-in decides, not every sound).
this.show({ heard: s.text, spoken: '', ...honest('listening') }, gen);
if (live.hushed && !live.stated) { live.hushed = false; live.room?.hush(false); }
return;
}
if (s.kind === 'user_final') {
// A new turn of yours: nothing of hers from before may stand after it.
if (live.speech) this.close(live, live.speech);
this.show({ heard: s.text, spoken: '', her: null, ...honest('thinking') }, gen); this.deps.onSpoke(); this.deps.onRecord();
return;
}
const pro = s.kind.startsWith('proactive_');
if (s.kind === 'turn_start' || s.kind === 'proactive_start') {
if (live.closed.has(s.speech) || live.speech === s.speech) return;
if (live.speech) this.close(live, live.speech);
live.speech = s.speech; live.pro = pro; live.message = s.messageId;
// A reach-out arrives whole (its stored text); a reply starts empty and grows.
this.show({ spoken: '', ...(pro ? { heard: '' } : {}), her: pro ? { speech: s.speech, text: s.text, state: 'open', messageId: s.messageId, proactive: true } : { speech: s.speech, text: '', state: 'open' }, ...honest(pro ? 'speaking' : 'thinking') }, gen);
return;
}
if (s.speech !== live.speech || pro !== live.pro || (pro && s.messageId !== live.message)) return;
const mine = cur?.speech === s.speech ? cur : null;
switch (s.kind) {
case 'assistant_interim':
// Replace, never append: each interim is the whole reply so far.
if (mine?.state === 'open' && mine.text !== s.text) this.show({ her: { ...mine, text: s.text } }, gen);
return;
case 'assistant_final':
if (mine?.state !== 'open') return;
// Her stored answer: your draft it answered has done its part (as before v2).
this.show({ heard: '', her: { ...mine, text: s.text, state: 'final', turnId: s.turnId }, ...honest('listening') }, gen); this.deps.onRecord();
return;
case 'error':
// φ: heard, not stored; her unfinished line goes at once. The cancel that follows closes the speech.
this.show({ heard: '', spoken: s.text, ...(mine ? { her: null } : {}), ...honest('listening') }, gen); this.deps.onRecord();
return;
case 'turn_end': case 'proactive_end':
this.close(live, s.speech);
// A reply closed without its final never became her reply; a reach-out read to the end stays until the
// record or the next turn takes its place.
this.show({ ...(mine ? { her: mine.state === 'final' || pro ? { ...mine, state: 'done' as const } : null } : {}), ...honest('listening') }, gen);
if (!pro) this.deps.onRecord();
return;
case 'turn_cancel': case 'proactive_cancel':
this.close(live, s.speech);
this.show({ ...(mine ? { her: null } : {}), ...honest('listening') }, gen);
if (!pro) this.deps.onRecord();
return;
}
}
private close(live: Live, speech: string) {
if (live.speech === speech) { live.speech = ''; live.pro = false; live.message = undefined; }
live.closed.add(speech);
}
// You sent text while she was answering by voice: the server cancels her voice turn; keep its last audio silent.
// Her line goes at once, whatever state it was in: your words come next on the stage.
hush() {
const live = this.live; if (!live) return;
if (live.speech) this.close(live, live.speech);
if (this.view.her) this.show({ her: null }, live.gen);
if (!live.room || (this.view.phase !== 'speaking' && this.view.phase !== 'thinking')) return;
live.hushed = true; live.room.hush(true);
this.show({ spoken: '' }, live.gen);
}
async resumeAudio() { const live = this.live; if (!live?.room) return; try { await live.room.resumeAudio(); this.show({ blocked: false }, live.gen); } catch { /* Still blocked; the tap stays offered. */ } }
private async teardown(live: Live, keepalive = false) {
live.abort.abort(); clearTimeout(live.timer);
try { live.mic?.stop(); } catch { /* Already stopped. */ }
const room = live.room; live.room = undefined;
const session = live.session; live.session = undefined;
const closing = room ? room.close().catch(() => {}) : Promise.resolve();
// The server deletes the room: her worker leaves and its job ends even if the page could not say goodbye itself.
// A DELETE that could not get through (offline) is kept and sent again when the network is back.
const ending = session ? this.release(session, keepalive) : Promise.resolve();
await Promise.all([closing, ending]);
}
// Kept in this browser (not only in memory), so leaving the conversation or reloading does not forget them. Until
// one gets through, the server keeps its own bounded cleanup ledger for the rooms it opened (retrying its delete,
// also across restarts, up to a bound), and the worker's job ends when the page's participant is gone from the
// room; an unanswered DELETE is NOT proof the room is gone — 404 means settled, anything else keeps the debt here
// (runbook-hel877-voice §3.4/§3.5, HEL-879: the old "the server side still ends on its own" was an unproven claim).
private owe(session: string, on: boolean) {
const list = new Set(owedSessions());
if (on) list.add(session); else list.delete(session);
try { if (list.size) localStorage.setItem(OWED, JSON.stringify([...list].slice(-20))); else localStorage.removeItem(OWED); } catch { /* Memory only for this visit. */ }
if (on) this.owed.add(session); else this.owed.delete(session);
}
private owed = new Set<string>();
private release(session: string, keepalive = false) {
// Noted before sending: if the page is gone before the answer, the next visit sends it again (404 = done).
this.owe(session, true);
return this.f(`/api/voice/session/${encodeURIComponent(session)}`, { method: 'DELETE', keepalive })
.then(r => { this.owe(session, !(r.ok || r.status === 404)); }, () => { this.owe(session, true); });
}
// Back online, arriving, or starting again: give back rooms an earlier end could not reach the server to delete.
async settle() { await Promise.all([...new Set([...this.owed, ...owedSessions()])].map(s => this.release(s))); }
}
// The record's view of voice: rows of your and her voice turns, re-read from the server. Her reach-outs (proactive)
// are left to the inbox reader so they keep their own entrance; text turns already on the page are matched by turn id.
export function mergeTurns(known: Message[], rows: Message[]): Message[] | null {
const byId = new Map(known.map((m, i) => [m.id, i])), turns = new Set(known.flatMap(m => m.turnId ? [`${m.role}:${m.turnId}`] : []));
let next: Message[] | null = null;
for (const m of [...rows].sort((a, b) => serverId(a) - serverId(b))) {
if (m.proactive || !serverId(m)) continue;
const at = byId.get(m.id);
if (at !== undefined) {
const old = (next ?? known)[at];
if (old.status !== m.status || old.text !== m.text) { next ??= [...known]; next[at] = { ...old, status: m.status, text: m.text }; }
continue;
}
if (m.turnId && turns.has(`${m.role}:${m.turnId}`)) continue;
next ??= [...known]; next.push(m); byId.set(m.id, next.length - 1); if (m.turnId) turns.add(`${m.role}:${m.turnId}`);
}
return next;
}
// Her voice line as the stage shows it, in the place her text reply would take; null once it has nothing to add.
// `since` is how many record rows there were when this speech was first seen. It gives way to the record: her reply
// once its own row (same turn) is there, a reach-out once its stored row is the newest line; a finished line also as
// soon as anything else came into the record after it, so it never stands in front of a newer turn.
export function voiceLine(her: HerLine | null, messages: Message[], since: number, incoming: Message[] = []): ShownMessage | null {
if (!her || !her.text) return null;
const own = (m: Message) => her.proactive ? m.id === String(her.messageId) : !!her.turnId && m.turnId === her.turnId;
if (her.proactive ? messages.at(-1)?.id === String(her.messageId) : messages.some(m => m.role === 'companion' && own(m))) return null;
if (her.state !== 'open' && messages.slice(since).some(m => !own(m))) return null;
// A reach-out keeps its stored row's identity (id, turn), so the row taking over keeps the same lines on the stage.
const row = her.proactive ? [...messages, ...incoming].find(own) : undefined;
// Her reply while she says it: every sentence she has finished is on the stage, only the one still forming waits.
return { id: row?.id ?? `voice-${her.speech}`, role: 'companion', text: her.text, lifeIds: [], turnId: row ? row.turnId : her.turnId, ...(her.proactive ? { proactive: true } : {}), ...(her.state === 'open' && !her.proactive ? { live: 'speaking' as const } : {}) };
}
// Newest rows down to `since` (exclusive), at most `pages` pages of 50. Voice turns are few per read; a longer gap is
// left to the next re-read rather than read without bound.
export async function recentRows(since: number, signal: AbortSignal, pages = 4): Promise<Message[]> {
const rows: Message[] = [];
let before: number | null = null;
for (let i = 0; i < pages; i++) {
const page: MessagePage = await api(`messages?limit=50${before ? `&before=${before}` : ''}`, { signal: within(signal, 10000) });
const list = (Array.isArray(page.messages) ? page.messages : []).filter(m => Number.isSafeInteger(m?.id) && m.id > 0 && typeof m.text === 'string');
rows.push(...list.filter(m => m.id > since).map(toMessage));
if (list.some(m => m.id <= since) || !page.next_before || !Number.isSafeInteger(page.next_before)) break;
before = page.next_before;
}
return rows;
}