@runtypelabs/persona 4.26.1 → 4.28.0

package/src/voice/runtype-voice-provider.ts

@@ -64,7 +64,25 @@
 // agent as conversation; a user bubble becomes conversation only when it is
 // submitted. With `context` negotiated, one `context{text}` frame (chat history
 // as of call start plus the host's `callContext`) is held until the visitor's
-// first final transcript or first delegation.
+// first final transcript or first delegation; a delegation's frames (deltas
+// and result) wait for it (up to 2 s, then it is dropped).
+//
+// Streaming (`delegation_stream` and `delegation_read_back` both negotiated,
+// with client delegation; the read-back tags are what keep a streamed answer
+// spoken as several utterances folded): while a
+// delegated turn renders, its assistant answer goes out as ordered
+// `delegation_delta{delegationId, text}` pieces (clause-sized, see
+// voice-clause-buffer.ts; approval cards, tool bubbles and captions never
+// stream), all before the delegation's first `delegation_update` or
+// `delegation_result`. That frame then carries `streamedChars`: how many
+// leading characters of its `text` the deltas already sent (an approval
+// script appended after the answer is the unstreamed rest). Absent or 0: none.
+// The server reports each spoken chunk with `delegation_progress{delegationId,
+// text}`; the first one of a spoken phase folds the read-back as
+// `delegation_completed{speak:true}` does (status stays "processing" until
+// completed), and that phase's completion doesn't fold another utterance.
+// Delegated sends carry `voice: { spoken: true }` on the chat request, so the
+// agent answers in speakable sentences.
 
 import type {
   VoiceProvider,
@@ -99,6 +117,8 @@ const LEVEL_RMS_SCALE = 4;
 const RIFF_MAGIC = 0x52494646; // "RIFF"
 /** `prewarm()` warms at most once per this window per provider instance. */
 const PREWARM_THROTTLE_MS = 30_000;
+/** How long a call start waits for a suspended capture context to run. */
+const AUDIO_RESUME_TIMEOUT_MS = 1_000;
 /** How long `startListening()` waits on an attach still handshaking. */
 const ATTACH_HANDSHAKE_TIMEOUT_MS = 5_000;
 /** Attached-socket idle window: server default and clamp range. */
@@ -142,6 +162,17 @@ const VOICE_PROTOCOL = "runtype-browser-v1";
 /** `approvalTimeoutMs` cap: below core's delegation deadline (600 s, restarted by each update). */
 const APPROVAL_TIMEOUT_MAX_MS = 540_000;
 const DISCLOSURE_TEXT = "You're talking to an AI assistant. Voice is processed by OpenAI.";
+/** Status-line text per `session_end.reason` (Amendment 6); unlisted reasons show nothing. */
+const SESSION_END_TEXT = new Map([
+  ["idle_timeout", "Voice call ended after a quiet period."],
+  ["max_duration", "This voice call reached its time limit."],
+  ["provider_ended", "The voice session ended."],
+  ["quota", "Voice is unavailable right now."],
+  ["auth_expired", "Voice session expired. Tap the mic to reconnect."],
+]);
+/** Reasons that get one automatic reconnect. */
+const RECONNECT_REASONS = ["provider_error", "server_restart"];
+const CONNECTION_LOST = "Voice connection lost.";
 /** Call-start context frame: total cap, host share, history window, per-message cap. */
 const CONTEXT_MAX_CHARS = 8000;
 const CONTEXT_HOST_MAX_CHARS = 4000;
@@ -271,6 +302,14 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #cancelledDelegations = new Set<string>();
   // session_config.callId: the server's id for this call, for logs.
   #callId: string | undefined;
+  // Amendment 6: why the server ended this call (its last frame), if it said.
+  #sessionEnd: { reason: string; message?: string } | null = null;
+  // Status-line text for the UI, read once (`takeNotice`).
+  #notice: string | null = null;
+  // One automatic reconnect per call the visitor started: pending, and spent.
+  #reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  #reconnected = false;
+  #autoReconnect = false;
   // Call-start context, built at session_config and held until the visitor's
   // first final transcript (sent earlier, the voice model tends to answer it).
   #contextSent = false;
@@ -278,8 +317,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   // The released context's send; settles once it went out (or never will).
   #contextSend: { done: Promise<void>; drop: () => void } | null = null;
   #delegations: Promise<void> = Promise.resolve();
-  // Delegations answered ok: their spoken read-back is folded.
+  // Delegations answered ok (or that streamed part of their answer): their
+  // spoken read-back is folded.
   #answered = new Set<string>();
+  // Delegations whose current spoken phase already folded on `delegation_progress`.
+  #progressed = new Set<string>();
+  // The delegation whose read-back `#foldReadback` is waiting for.
+  #foldArmedBy: string | null = null;
   #foldReadback = false;
   #assistantTurns = new Set<string>();
   #foldedTurns = new Set<string>();
@@ -452,7 +496,7 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #voiceSocketUrl(host: string, agentId: string, attach?: URLSearchParams): string {
     const capabilities = ["partial_transcript", "context"];
     if (this.bridge && this.config?.clientDelegation !== false)
-      capabilities.push("client_delegation", "delegation_update", "delegation_read_back");
+      capabilities.push("client_delegation", "delegation_update", "delegation_read_back", "delegation_stream");
     if (attach) capabilities.unshift("attach");
     const params = new URLSearchParams({
       voiceProtocol: VOICE_PROTOCOL,
@@ -467,6 +511,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   /** Start the call: acquire mic, open the WS, stream PCM until hang-up. */
   async startListening(): Promise<void> {
     if (this.#callLive) return; // idempotent: a call is already live
+    // A call the visitor starts gets a fresh reconnect; the automatic one doesn't.
+    const auto = this.#autoReconnect;
+    if (!auto) {
+      this.#reconnected = false;
+      this.#notice = null;
+    }
+    this.#autoReconnect = false;
 
     const agentId = this.config?.agentId;
     const token = this.config?.clientToken;
@@ -499,10 +550,22 @@ export class RuntypeVoiceProvider implements VoiceProvider {
       const captureContext: AudioContext = new AudioCtx({
         sampleRate: CAPTURE_SAMPLE_RATE,
       });
+      this.#captureContext = captureContext;
       if (captureContext.state === "suspended") {
-        await captureContext.resume().catch(() => {});
+        // Outside a click (the automatic reconnect, or a call restored after a
+        // page navigation) the autoplay policy can leave audio suspended and
+        // `resume()` pending forever: fail fast rather than hang or open a dead call.
+        await Promise.race([
+          captureContext.resume().catch(() => {}),
+          new Promise((resolve) => setTimeout(resolve, auto ? 500 : AUDIO_RESUME_TIMEOUT_MS)),
+        ]);
+        if (generation !== this.#callGeneration) return; // hung up meanwhile
+        if ((captureContext.state as string) !== "running") {
+          if (auto) throw new Error((this.#notice = `${CONNECTION_LOST} Tap the mic to reconnect.`));
+          // A restored call: the widget asks for a tap to resume.
+          throw new Error("Audio blocked until a tap");
+        }
       }
-      this.#captureContext = captureContext;
 
       const engine = this.config?.createPlaybackEngine
         ? await this.config.createPlaybackEngine()
@@ -560,7 +623,8 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     ws.onmessage = (event) => this.#handleMessage(event, generation);
 
     ws.onerror = () => {
-      if (generation !== this.#callGeneration) return;
+      // After `session_end`, the close that follows reports the server's reason.
+      if (generation !== this.#callGeneration || this.#sessionEnd) return;
       this.#emitError(new Error("Voice connection failed"));
       this.#emitStatus("error");
       this.#cleanup();
@@ -572,17 +636,68 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         return;
       }
       if (generation !== this.#callGeneration) return;
-      if (evt.code !== 1000) {
-        const codeMsg = evt.code ? ` (code ${evt.code})` : "";
-        this.#emitError(new Error(`Voice connection closed${codeMsg}`));
-        this.#emitStatus("error");
-      } else {
-        this.#emitStatus("idle");
+      // Why the server ended it: its `session_end`, or the attach idle close.
+      const end = this.#sessionEnd ?? (evt.code === 4408 ? { reason: "idle_timeout" } : null);
+      if (!end) {
+        // No reason given (a deploy, a dropped connection): as before.
+        if (evt.code !== 1000) {
+          const codeMsg = evt.code ? ` (code ${evt.code})` : "";
+          this.#emitError(new Error(`Voice connection closed${codeMsg}`));
+          this.#emitStatus("error");
+        } else {
+          this.#emitStatus("idle");
+        }
+        this.#cleanup();
+        return;
       }
-      this.#cleanup();
+      this.#endCall(end.reason, end.message);
     };
   }
 
+  /**
+   * The server ended the call with a reason (`session_end`, Amendment 6): show
+   * its text, and reconnect once after a provider error or a restart. Unknown
+   * reasons are an ordinary end (`ended_by_server`).
+   */
+  #endCall(reason: string, message?: string): void {
+    const retry = RECONNECT_REASONS.includes(reason) && !this.#reconnected;
+    this.#cleanup();
+    if (retry) {
+      // Keep the call "live" while it waits, so the mic button hangs up (and cancels).
+      this.#reconnected = true;
+      this.#callLive = true;
+      this.#notice = reason === "provider_error" ? `${CONNECTION_LOST} Reconnecting…` : "Reconnecting…";
+      // A hang-up meanwhile runs #cleanup, which clears this timer.
+      this.#reconnectTimer = setTimeout(
+        () => {
+          this.#callLive = false;
+          this.#autoReconnect = true;
+          void this.startListening().catch(() => {});
+        },
+        1000 + Math.random() * 1000,
+      );
+      this.#emitStatus("idle");
+      return;
+    }
+    if (RECONNECT_REASONS.includes(reason)) {
+      // The reconnect already ran: this end is the second failure.
+      this.#notice = CONNECTION_LOST;
+      this.#emitError(new Error(CONNECTION_LOST));
+      return this.#emitStatus("error");
+    }
+    // `error`: the preceding `error` frame already reported it.
+    if (reason === "error") return this.#emitStatus("error");
+    this.#notice = (reason === "quota" && message) || SESSION_END_TEXT.get(reason) || null;
+    this.#emitStatus("idle");
+  }
+
+  /** Status-line text for the call (why it ended, or that it is reconnecting), once. */
+  takeNotice(): string | null {
+    const notice = this.#notice;
+    this.#notice = null;
+    return notice;
+  }
+
   /** The AI-disclosure notice for a live speech-to-speech call (`disclosureText`; `false` hides it). */
   getDisclosure(): string | null {
     const text = this.config?.disclosureText;
@@ -757,6 +872,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
             const tag = msg.delegationId;
             if (typeof tag === "string" && this.#answered.has(tag) && !this.#assistantTurns.has(turnId)) {
               this.#foldedTurns.add(turnId);
+              this.#foldReadback = false;
+            } else if (this.#foldReadback && !this.#assistantTurns.has(turnId)) {
+              // Armed by `delegation_progress`: the server may leave the
+              // read-back untagged (it continued a filler it cut), so the
+              // first new utterance after it is the read-back.
+              this.#foldedTurns.add(turnId);
+              this.#foldReadback = false;
             }
           } else if (this.#foldReadback && !this.#assistantTurns.has(turnId)) {
             this.#foldedTurns.add(turnId);
@@ -799,8 +921,13 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         } else if (msg.speak !== false && this.#answered.has(delegationId)) {
           // Every spoken phase (the approval ask, the late result) of an answer
           // the chat shows is read back. A refusal of one that never started
-          // here has no chat answer: it renders. `final` may never come.
-          this.#foldReadback = true;
+          // here has no chat answer: it renders. `final` may never come. A
+          // phase whose first `delegation_progress` already armed the fold
+          // ends here without arming it again. With `delegation_read_back`
+          // the tag marks the read-back, so completion arms nothing (only
+          // progress does, for a read-back the server left untagged).
+          if (!this.#progressed.delete(delegationId) && !this.#capabilities.has("delegation_read_back"))
+            this.#armFold(delegationId);
         }
         this.#delegating = msg.type === "delegation_started";
         if (!this.#isSpeaking && !this.#isCancelling()) {
@@ -809,6 +936,23 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         break;
       }
 
+      case "delegation_progress": {
+        // The server handed a spoken chunk of this delegation to the voice
+        // model: its read-back is starting. The first one of a phase folds it,
+        // as `delegation_completed{speak:true}` does; later ones (and that
+        // phase's completion) don't fold another utterance. Still delegating.
+        const delegationId = String(msg.delegationId);
+        if (
+          this.#answered.has(delegationId) &&
+          !this.#progressed.has(delegationId) &&
+          !this.#cancelledDelegations.has(delegationId)
+        ) {
+          this.#progressed.add(delegationId);
+          this.#armFold(delegationId);
+        }
+        break;
+      }
+
       case "delegation_cancelled":
         // The server gave up on it: no more frames for it, and its approval
         // timers stop. The chat turn still renders. Past its deadline (or for
@@ -872,6 +1016,14 @@ export class RuntypeVoiceProvider implements VoiceProvider {
         this.#emitError(new Error(msg.error || "Voice error"));
         this.#emitStatus("error");
         break;
+
+      case "session_end":
+        // The server's last frame before it closes: the close acts on it.
+        this.#sessionEnd = {
+          reason: String(msg.reason),
+          ...(typeof msg.message === "string" && { message: msg.message }),
+        };
+        break;
     }
   }
 
@@ -921,9 +1073,19 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     if (timedOut) send.drop();
   }
 
+  /** The next new assistant utterance is this delegation's read-back: fold it. */
+  #armFold(delegationId: string): void {
+    this.#foldReadback = true;
+    this.#foldArmedBy = delegationId;
+  }
+
   /** No more frames for this delegation; its chat answer goes back to browser TTS. */
   #dropDelegation(delegationId: string, expired = false): void {
     this.#cancelledDelegations.add(delegationId);
+    // A fold it armed whose read-back never started would hide the next
+    // unrelated utterance: disarm it.
+    if (this.#foldArmedBy === delegationId) this.#foldReadback = false;
+    this.#progressed.delete(delegationId);
     this.bridge?.dropDelegation?.(delegationId, expired);
     this.#followUps.get(delegationId)?.abort();
   }
@@ -932,28 +1094,46 @@ export class RuntypeVoiceProvider implements VoiceProvider {
   #runDelegation(delegationId: string, request: VoiceDelegationRequest, generation: number): void {
     const bridge = this.bridge!;
     /** Send a frame for this delegation, unless the call or the delegation ended. */
-    const send = (type: "delegation_update" | "delegation_result", status: string, text: string) => {
+    const send = ({ type, ...fields }: Record<string, unknown> & { type: string }) => {
       const ws = this.#ws;
       if (generation !== this.#callGeneration || ws?.readyState !== WebSocket.OPEN) return false;
       if (this.#cancelledDelegations.has(delegationId)) return false;
-      ws.send(JSON.stringify({ type, delegationId, status, text }));
+      ws.send(JSON.stringify({ type, delegationId, ...fields }));
       return true;
     };
+    const answer = (type: "delegation_update" | "delegation_result", status: string, text: string, streamedChars = 0) =>
+      send({ type, status, text, ...(streamedChars > 0 && { streamedChars }) });
     this.#delegations = this.#delegations.then(async () => {
       // Cancelled while queued behind another turn: never start it.
       if (generation !== this.#callGeneration || this.#cancelledDelegations.has(delegationId)) return;
+      // Streaming (`delegation_stream`): the answer goes out as
+      // `delegation_delta` pieces while the chat renders it, after the call
+      // context, and all of them before the result.
+      let deltas: Promise<void> | null = null;
+      // Only with read-back tags: a streamed answer can be spoken as several
+      // utterances, and the tags are what keep all of them folded.
+      const streaming = this.#capabilities.has("delegation_stream") && this.#capabilities.has("delegation_read_back");
+      const stream = (text: string) => {
+        deltas = (deltas ?? this.#awaitContextSend()).then(() => {
+          // The chat shows what was streamed: its read-back is folded.
+          if (send({ type: "delegation_delta", text })) this.#answered.add(delegationId);
+        });
+      };
       const result: VoiceDelegationResult = await bridge
-        .runDelegatedTurn(request)
+        .runDelegatedTurn(streaming ? { ...request, stream } : request)
         .catch(() => ({ status: "failed", text: "" }));
       await this.#awaitContextSend();
+      await deltas;
+      const streamedChars = streaming ? (result.streamedChars ?? 0) : 0;
       // Parked on an approval: ask now (non-terminal), answer once the visitor
       // decides. A server that can't take an update gets the ask as the result.
       const parked = !!result.followUp;
       const update = parked && this.#capabilities.has("delegation_update");
-      const sent = send(
+      const sent = answer(
         update ? "delegation_update" : "delegation_result",
         parked && !update ? "completed" : result.status,
         result.text,
+        streamedChars,
       );
       if (!sent) return;
       if (result.status !== "failed" && result.inChat !== false) this.#answered.add(delegationId);
@@ -968,12 +1148,12 @@ export class RuntypeVoiceProvider implements VoiceProvider {
           approvalTimeoutMs: this.config?.approvalTimeoutMs && Math.min(this.config.approvalTimeoutMs, APPROVAL_TIMEOUT_MAX_MS),
           readBack: update,
           // Another gated tool in the same turn: another (non-terminal) update.
-          onUpdate: (text) => send("delegation_update", "pending_approval", text),
+          onUpdate: (text) => answer("delegation_update", "pending_approval", text),
         })
         .then((followUp) => {
           this.#followUps.delete(delegationId);
           // Hang-up and cancellation send nothing.
-          if (update && followUp && !abort.signal.aborted) send("delegation_result", followUp.status, followUp.text);
+          if (update && followUp && !abort.signal.aborted) answer("delegation_result", followUp.status, followUp.text);
         });
     });
   }
@@ -1063,11 +1243,15 @@ export class RuntypeVoiceProvider implements VoiceProvider {
     this.#followUps.clear();
     this.#cancelledDelegations.clear();
     this.#callId = undefined;
+    this.#sessionEnd = null;
+    clearTimeout(this.#reconnectTimer);
     this.#contextSent = false;
     this.#pendingContext = null;
     this.#contextSend = null;
     this.#delegations = Promise.resolve();
     this.#answered.clear();
+    this.#progressed.clear();
+    this.#foldArmedBy = null;
     this.#foldReadback = false;
     this.#assistantTurns.clear();
     this.#foldedTurns.clear();

package/src/voice/voice-clause-buffer.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it } from "vitest";
+import { CLAUSE_MAX_CHARS, ClauseBuffer } from "./voice-clause-buffer";
+
+/** Push `chunks` one by one, then flush; returns every piece in order. */
+function run(chunks: string[]): string[] {
+  const buffer = new ClauseBuffer();
+  const pieces = chunks.flatMap((chunk) => buffer.push(chunk));
+  return [...pieces, ...buffer.flush()];
+}
+
+/** Push character by character (the worst case for boundary detection). */
+const byChar = (text: string) => run([...text]);
+
+describe("ClauseBuffer", () => {
+  it("emits the first piece at a clause mark, then whole sentences", () => {
+    expect(byChar("Sure, we open at eight. On Sundays we are closed. Anything else?")).toEqual([
+      "Sure, ",
+      "we open at eight. ",
+      "On Sundays we are closed. ",
+      "Anything else?",
+    ]);
+  });
+
+  it("does not split later pieces at clause marks", () => {
+    expect(byChar("Yes. Monday, Tuesday, and Friday work; Sunday doesn't. Done")).toEqual([
+      "Yes. ",
+      "Monday, Tuesday, and Friday work; Sunday doesn't. ",
+      "Done",
+    ]);
+  });
+
+  it("emits the first piece after ~30 characters or 6 words without punctuation", () => {
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("We bake sourdough rye ")).toEqual([]);
+    expect(buffer.push("and a seeded loaf every")).toEqual(["We bake sourdough rye and a seeded loaf "]);
+    expect(buffer.push(" morning")).toEqual([]);
+    expect(buffer.flush()).toEqual(["every morning"]);
+
+    const words = new ClauseBuffer();
+    expect(words.push("a b c d e f ")).toEqual(["a b c d e f "]);
+  });
+
+  it("keeps a whole first sentence together when it arrives before its trailing space", () => {
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("I can place that order for you.")).toEqual([]);
+    expect(buffer.flush()).toEqual(["I can place that order for you."]);
+    expect(run(["I can place that order for you.", " Shall I?"])).toEqual(["I can place that order for you. ", "Shall I?"]);
+  });
+
+  it("keeps abbreviations, initials, decimals and list numbers inside a sentence", () => {
+    expect(
+      byChar("Hi there. Dr. Smith and J. R. Lee arrive at 9 a.m. today, e.g. for 3.5 hours. Then we close."),
+    ).toEqual(["Hi there. ", "Dr. Smith and J. R. Lee arrive at 9 a.m. today, e.g. for 3.5 hours. ", "Then we close."]);
+    expect(byChar("Steps:\n1. Mix the flour.\n2. Bake it.")).toEqual([
+      "Steps:\n",
+      "1. Mix the flour.\n",
+      "2. Bake it.",
+    ]);
+    expect(byChar("Please call 911. It is urgent.")).toEqual(["Please call 911. ", "It is urgent."]);
+  });
+
+  it("treats line breaks (Markdown blocks and list items) as boundaries", () => {
+    expect(byChar("**Opening hours**\n\n- Monday to Friday: 8am to 6pm\n- Sunday: closed")).toEqual([
+      "**Opening hours**\n\n",
+      "- Monday to Friday: 8am to 6pm\n",
+      "- Sunday: closed",
+    ]);
+  });
+
+  it("keeps closing quotes and emphasis with their sentence", () => {
+    expect(byChar('He said "go." Then **we left.** Fine')).toEqual(['He said "go." ', "Then **we left.** ", "Fine"]);
+    expect(byChar("Really?! Yes")).toEqual(["Really?! ", "Yes"]);
+  });
+
+  it("waits for whitespace after a period before cutting", () => {
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("It costs 3.")).toEqual([]);
+    expect(buffer.push("50 dollars. And")).toEqual(["It costs 3.50 dollars. "]);
+  });
+
+  it("caps pieces at the max length, cutting at a clause mark, then a word, then hard", () => {
+    const clauses = `${"word ".repeat(30)}and then, ${"more ".repeat(30)}end.`;
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("Hi. ")).toEqual([]); // the whitespace may still grow
+    const [hi, ...pieces] = [...buffer.push(clauses), ...buffer.flush()];
+    expect(hi).toBe("Hi. ");
+    expect(pieces.every((p) => p.length <= CLAUSE_MAX_CHARS)).toBe(true);
+    expect(pieces[0]).toMatch(/and then, $/);
+    expect(pieces.join("")).toBe(clauses);
+
+    const words = run(["Ok. ", "abcd ".repeat(100)]);
+    expect(words.slice(1).every((p) => p.length <= CLAUSE_MAX_CHARS && /\s$/.test(p))).toBe(true);
+
+    const solid = run(["x".repeat(500)]);
+    expect(solid.map((p) => p.length)).toEqual([CLAUSE_MAX_CHARS, CLAUSE_MAX_CHARS, 60]);
+  });
+
+  it("never cuts inside a surrogate pair", () => {
+    const text = `${"x".repeat(CLAUSE_MAX_CHARS - 1)}😀${"y".repeat(10)}`;
+    const pieces = run([text]);
+    expect(pieces.join("")).toBe(text);
+    expect(pieces[0]).toBe("x".repeat(CLAUSE_MAX_CHARS - 1));
+  });
+
+  it("pieces always concatenate to the input, however it is chunked", () => {
+    const text =
+      "**Opening hours**\n\n- Monday to Friday: 8am to 6pm\n- Saturday: 9am to 4pm\n\nWe're on Main St. near the U.S. post office, e.g. by the park. Call us!  ";
+    for (const size of [1, 2, 3, 7, 13, 40, text.length]) {
+      const chunks: string[] = [];
+      for (let i = 0; i < text.length; i += size) chunks.push(text.slice(i, i + size));
+      const pieces = run(chunks);
+      const joined = pieces.join("");
+      expect(text.startsWith(joined)).toBe(true);
+      expect(joined.trimEnd()).toBe(text.trimEnd());
+      expect(pieces.every((p) => p.trim().length > 0 && p.length <= CLAUSE_MAX_CHARS)).toBe(true);
+    }
+  });
+
+  it("idle() releases held text that ends in a terminator, and nothing else", () => {
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("We're open Monday to Friday from 8am to 6pm.")).toEqual([]);
+    expect(buffer.idle()).toEqual(["We're open Monday to Friday from 8am to 6pm."]);
+    expect(buffer.idle()).toEqual([]);
+    expect(buffer.push(" On Saturdays we open")).toEqual([]);
+    expect(buffer.idle()).toEqual([]); // no terminator: keep waiting
+    expect(buffer.push(" at 9 a.m.")).toEqual([]);
+    expect(buffer.idle()).toEqual([" On Saturdays we open at 9 a.m."]); // no guards on a pause
+    for (const ending of ["Really?!", 'He said "go."', "**Done.**", "Wait…", "Line\n"]) {
+      const b = new ClauseBuffer();
+      b.push(ending);
+      expect(b.idle()).toEqual([ending]);
+    }
+  });
+
+  it("emits nothing for whitespace only, and flush empties the buffer", () => {
+    const buffer = new ClauseBuffer();
+    expect(buffer.push("   ")).toEqual([]);
+    expect(buffer.flush()).toEqual([]);
+    expect(buffer.push("Hello")).toEqual([]);
+    expect(buffer.flush()).toEqual(["Hello"]);
+    expect(buffer.flush()).toEqual([]);
+  });
+});