openai 7.14.0 → 7.16.0

package/src/internal/utils/abort.ts

@@ -0,0 +1,111 @@
+type AbortCallback = () => void;
+interface WeakReference<T> {
+  deref: () => T | undefined;
+}
+type WeakAbortCallback = WeakReference<AbortCallback>;
+interface AbortFinalizer {
+  register: (target: AbortCallback, cleanup: AbortCallback, token: object) => void;
+  unregister: (token: object) => boolean;
+}
+
+// Keep these optional runtime features out of the SDK's ES2020 type requirements.
+const weakGlobals = globalThis as typeof globalThis & {
+  WeakRef?: new <T extends object>(target: T) => WeakReference<T>;
+  FinalizationRegistry?: new (cleanup: (value: AbortCallback) => void) => AbortFinalizer;
+};
+const finalizer =
+  typeof weakGlobals.FinalizationRegistry === 'function'
+    ? new weakGlobals.FinalizationRegistry((cleanup) => {
+        try {
+          cleanup();
+        } catch {
+          // Caller-provided signal methods must not throw out of a GC callback.
+        }
+      })
+    : undefined;
+const callbackOwners = new WeakMap<object, Set<AbortCallback>>();
+const subscriptions = new WeakMap<AbortSignal, { callbacks: Set<WeakAbortCallback>; abort: AbortCallback }>();
+
+// This scope receives only a weak reference, so its closures cannot retain the callback.
+function subscribeWeakly(signal: AbortSignal, reference: WeakAbortCallback, registry: AbortFinalizer) {
+  let subscription = subscriptions.get(signal);
+  if (!subscription) {
+    const callbacks = new Set<WeakAbortCallback>();
+    const abort = () => {
+      subscriptions.delete(signal);
+      for (const callback of callbacks) {
+        registry.unregister(callback);
+        callback.deref()?.();
+      }
+      callbacks.clear();
+    };
+    subscription = { callbacks, abort };
+    signal.addEventListener('abort', abort, { once: true });
+    subscriptions.set(signal, subscription);
+  }
+  const owner = subscription;
+  owner.callbacks.add(reference);
+  return () => {
+    owner.callbacks.delete(reference);
+    registry.unregister(reference);
+    if (owner.callbacks.size === 0) {
+      if (subscriptions.get(signal) === owner) {
+        subscriptions.delete(signal);
+      }
+      signal.removeEventListener('abort', owner.abort);
+    }
+  };
+}
+
+// The listener must not retain the shared owner or its other request callbacks.
+function releaseOnAbort(
+  signal: AbortSignal,
+  callbacks: WeakReference<Set<AbortCallback>>,
+  abort: AbortCallback,
+) {
+  signal.addEventListener('abort', () => callbacks.deref()?.delete(abort), { once: true });
+}
+
+/** Keep cancellation alive until abort or collection of the response body or bodyless custom response. */
+export function retainRequestAbortCallback(
+  owner: object,
+  abort: AbortCallback,
+  requestSignal: AbortSignal,
+): void {
+  if (typeof weakGlobals.WeakRef === 'function' && finalizer && !requestSignal.aborted) {
+    let callbacks = callbackOwners.get(owner);
+    if (!callbacks) {
+      callbacks = new Set();
+      callbackOwners.set(owner, callbacks);
+    }
+    callbacks.add(abort);
+    releaseOnAbort(requestSignal, new weakGlobals.WeakRef(callbacks), abort);
+  }
+}
+
+/**
+ * Share one caller listener without it retaining completed requests. Collection removes
+ * weak subscriptions eventually; a live response body or custom response retains its callback.
+ * Runtimes without weak references keep the existing listener-based behavior.
+ */
+export function addRequestAbortListener(
+  signal: AbortSignal,
+  abort: AbortCallback,
+  requestSignal: AbortSignal,
+): AbortCallback {
+  if (signal.aborted) {
+    abort();
+    return () => {
+      // No listener was installed for an already aborted signal.
+    };
+  }
+  if (typeof weakGlobals.WeakRef !== 'function' || !finalizer) {
+    signal.addEventListener('abort', abort, { once: true });
+    return () => signal.removeEventListener('abort', abort);
+  }
+  const reference = new weakGlobals.WeakRef(abort);
+  const cleanup = subscribeWeakly(signal, reference, finalizer);
+  finalizer.register(abort, cleanup, reference);
+  retainRequestAbortCallback(requestSignal, abort, requestSignal);
+  return cleanup;
+}

package/src/internal/ws.ts

@@ -1,4 +1,26 @@
 import { concatBytes, encodeUTF8 } from './utils/bytes';
+import { OpenAIError } from '../core/error';
+
+/** Options for an independently buffered WebSocket stream iterator. */
+export interface WebSocketStreamOptions {
+  /**
+   * Maximum queued records, including raw data, errors and lifecycle events.
+   * Must be a positive safe integer. Omitted means unlimited. Overflow discards
+   * this iterator's backlog and rejects its next() calls with a WebSocketError,
+   * without closing the shared socket or affecting other iterators.
+   * This bounds event count, not payload bytes or total memory.
+   */
+  maxBufferedEvents?: number | undefined;
+}
+
+/** Snapshots and validates the iterator's limit before listeners are attached. */
+export function getMaxBufferedEvents(options?: WebSocketStreamOptions): number | undefined {
+  const limit = options?.maxBufferedEvents;
+  if (limit !== undefined && (!Number.isSafeInteger(limit) || limit <= 0)) {
+    throw new OpenAIError('maxBufferedEvents must be a positive safe integer');
+  }
+  return limit;
+}
 
 /** Reconnection event passed to the `onReconnecting` handler and event listeners. */
 export interface ReconnectingEvent<Parameters = Record<string, unknown>> {

package/src/lib/agents/agent-session-stream.ts

@@ -0,0 +1,326 @@
+import { TurnState } from './turn-state';
+import { APIUserAbortError, BadRequestError, OpenAIError } from '../../core/error';
+import type { Stream } from '../../core/streaming';
+import { buildHeaders } from '../../internal/headers';
+import type { RequestOptions } from '../../internal/request-options';
+import { uuid4 } from '../../internal/utils/uuid';
+import { hasOwn, isObj } from '../../internal/utils/values';
+import type {
+  AgentFunctionCallItem,
+  AgentFunctionCallOutputParam,
+  AgentSessionEvent,
+  AgentSessionInputMessageParam,
+  AgentSessionInputParam,
+  InputContentParam,
+} from '../../resources/beta/agents/agents';
+import type { Sessions } from '../../resources/beta/agents/sessions/sessions';
+
+/** A function result; object results are serialized as JSON text. */
+export type AgentToolOutput = AgentFunctionCallOutputParam | object | null;
+/** Receives a detached JSON object and may return a result asynchronously. */
+export type AgentToolHandler = (
+  arguments_: Record<string, unknown>,
+) => AgentToolOutput | PromiseLike<AgentToolOutput>;
+
+/** Input and optional sequential tool handlers for one turn on an idle session. */
+export interface AgentSessionStreamParams {
+  /** User messages, or text normalized to a single user message. Must not be empty. */
+  input: string | AgentSessionInputMessageParam[];
+  /** Registered functions run after their call event is yielded; unknown functions remain manual. */
+  toolHandlers?: Record<string, AgentToolHandler>;
+  /** Key for the input submission only; request headers take precedence, case-insensitively. */
+  idempotencyKey?: string;
+}
+
+type ToolResult = AgentSessionInputParam.SessionInputParamAgentSessionInputToolResult;
+
+function isInputContent(value: unknown): value is InputContentParam {
+  if (!isObj(value)) {
+    return false;
+  }
+  const content = value;
+  let field: string;
+  if (content['type'] === 'input_text') {
+    field = 'text';
+  } else if (content['type'] === 'input_image') {
+    field = 'image_url';
+  } else {
+    return false;
+  }
+  return hasOwn(content, 'type') && hasOwn(content, field) && typeof content[field] === 'string';
+}
+
+function normalizedOutput(value: unknown): AgentFunctionCallOutputParam | null {
+  if (value === null) {
+    return null;
+  }
+  if (typeof value === 'string' || (Array.isArray(value) && value.every(isInputContent))) {
+    return value;
+  }
+  throw new OpenAIError('Tool output must be text, content, a JSON object, or null');
+}
+
+function toolResult(call: AgentFunctionCallItem, value: AgentToolOutput): ToolResult {
+  const output =
+    value !== null && typeof value === 'object' && !Array.isArray(value) ? JSON.stringify(value) : value;
+  // Detect unserializable callback results inside the redacted failure boundary.
+  const serialized = JSON.stringify(output);
+  if (serialized === undefined) {
+    throw new OpenAIError('Tool output must be JSON serializable');
+  }
+  return {
+    type: 'agent.session.input.tool_result',
+    turn_id: call.turn_id,
+    call_id: call.call_id,
+    success: true,
+    output: normalizedOutput(typeof output === 'string' ? output : JSON.parse(serialized)),
+  };
+}
+
+async function cancelBody(response: Response | undefined): Promise<void> {
+  try {
+    await response?.body?.cancel();
+  } catch {
+    // The response may already be cancelled or owned by its stream reader.
+  }
+}
+
+/**
+ * A single-use, lazy async iterable of original session events for one turn.
+ * Requires an idle session and a single input writer: the input endpoint does not
+ * return a turn ID. Subscribe-before-input avoids losing events; the first
+ * coordinator turn selects the turn to follow. Initial idle events and subagent
+ * completion do not end iteration. A selected turn's terminal event followed by
+ * session.idle, or session.failed, ends iteration. Unexpected EOF throws.
+ *
+ * Tool handlers run sequentially during iteration. Handler failures submit a
+ * generic error without exception text. Each submission has a distinct retry-safe
+ * idempotency key. Breaking iteration or calling abort closes local requests;
+ * neither cancels the backend turn. No work starts until iteration begins.
+ */
+export class AgentSessionStream implements AsyncIterable<AgentSessionEvent> {
+  /** Aborts local requests and iteration without cancelling the backend turn. */
+  readonly controller = new AbortController();
+  #consumed = false;
+  #stream: Stream<AgentSessionEvent> | undefined;
+  #response: Response | undefined;
+  #reading = false;
+  #sessions: Sessions;
+  #sessionID: string;
+  #input: AgentSessionInputParam.SessionInputParamAgentSessionInputMessage;
+  #handlers: Map<string, AgentToolHandler>;
+  #inputKey: string | undefined;
+  #options: RequestOptions;
+
+  /** Creates an unstarted helper. Prefer client.beta.agents.sessions.stream(). */
+  constructor(
+    sessions: Sessions,
+    sessionID: string,
+    params: AgentSessionStreamParams,
+    options?: RequestOptions,
+  ) {
+    const input: AgentSessionInputMessageParam[] =
+      typeof params.input === 'string'
+        ? [{ role: 'user', content: [{ type: 'input_text', text: params.input }] }]
+        : params.input;
+    if (params.input.length === 0) {
+      throw new OpenAIError('input must not be empty');
+    }
+    this.#sessions = sessions;
+    this.#sessionID = sessionID;
+    this.#input = { type: 'agent.session.input.message', input };
+    this.#handlers = new Map(Object.entries(params.toolHandlers ?? {}));
+    const headers = buildHeaders([options?.headers]);
+    this.#inputKey = headers.nulls.has('idempotency-key')
+      ? undefined
+      : (headers.values.get('idempotency-key') ??
+        params.idempotencyKey ??
+        options?.idempotencyKey ??
+        uuid4());
+    headers.values.delete('idempotency-key');
+    headers.nulls.delete('idempotency-key');
+    const { idempotencyKey: _key, ...rest } = options ?? {};
+    this.#options = { ...rest, headers };
+  }
+
+  /** Closes local requests without cancelling the turn; an optional reason becomes the abort error's cause. */
+  abort(reason?: unknown): void {
+    this.controller.abort(reason);
+    this.#stream?.controller.abort(this.controller.signal.reason);
+    if (!this.#reading) {
+      void cancelBody(this.#response);
+    }
+  }
+
+  /** Starts iteration once; use for await to ensure early exits close the connection. */
+  [Symbol.asyncIterator](): AsyncIterator<AgentSessionEvent> {
+    if (this.#consumed) {
+      throw new OpenAIError('An AgentSessionStream can only be consumed once');
+    }
+    this.#consumed = true;
+    return this.#iterate();
+  }
+
+  async *#iterate(): AsyncGenerator<AgentSessionEvent> {
+    const externalSignal = this.#options.signal;
+    const abort = () =>
+      this.abort(externalSignal?.aborted ? externalSignal.reason : this.controller.signal.reason);
+    externalSignal?.addEventListener('abort', abort, { once: true });
+    this.controller.signal.addEventListener('abort', abort, { once: true });
+    const options = { ...this.#options, signal: this.controller.signal };
+    const state = new TurnState();
+    try {
+      if (externalSignal?.aborted) {
+        this.abort(externalSignal.reason);
+      }
+      this.#checkAbort();
+      const session = await this.#sessions.retrieve(this.#sessionID, options);
+      if (session.status !== 'idle') {
+        throw new OpenAIError(
+          'sessions.stream requires an idle session; use sessions.events.stream for active sessions',
+        );
+      }
+      const subscription = await this.#sessions.events.stream(this.#sessionID, options).withResponse();
+      this.#stream = subscription.data;
+      this.#response = subscription.response;
+      this.#checkAbort();
+      await this.#sessions.events.create(
+        this.#sessionID,
+        {
+          events: [this.#input],
+          ...(this.#inputKey === undefined ? {} : { 'Idempotency-Key': this.#inputKey }),
+        },
+        {
+          ...options,
+          headers: buildHeaders([options.headers, { 'Idempotency-Key': this.#inputKey ?? null }]),
+        },
+      );
+      this.#checkAbort();
+      this.#reading = true;
+      for await (const event of this.#stream) {
+        this.#checkAbort();
+        if (!state.accept(event)) {
+          continue;
+        }
+        const terminal = state.terminal(event);
+        const pendingCall = state.call(event);
+        const handler = pendingCall && this.#handlers.get(pendingCall.name);
+        // Freeze dispatch identity and arguments before exposing the original event.
+        const call = pendingCall && handler ? structuredClone(pendingCall) : undefined;
+        if (terminal) {
+          this.#stream.controller.abort();
+        }
+        yield event;
+        if (terminal) {
+          return;
+        }
+        this.#checkAbort();
+        if (!call || !handler) {
+          continue;
+        }
+        const result = await this.#result(call, handler);
+        this.#checkAbort();
+        await this.#submit(result, options);
+      }
+      this.#checkAbort();
+      throw new OpenAIError('Session event stream ended before the turn reached idle or failed');
+    } finally {
+      externalSignal?.removeEventListener('abort', abort);
+      this.controller.signal.removeEventListener('abort', abort);
+      this.abort();
+    }
+  }
+
+  async #result(call: AgentFunctionCallItem, handler: AgentToolHandler): Promise<ToolResult> {
+    try {
+      const args: unknown = typeof call.arguments === 'string' ? JSON.parse(call.arguments) : call.arguments;
+      if (args === null || typeof args !== 'object' || Array.isArray(args)) {
+        throw new OpenAIError('Function arguments must be a JSON object');
+      }
+      return toolResult(call, await this.#wait(() => handler(args as Record<string, unknown>)));
+    } catch {
+      this.#checkAbort();
+      return {
+        type: 'agent.session.input.tool_result',
+        turn_id: call.turn_id,
+        call_id: call.call_id,
+        success: false,
+        error: 'Tool handler failed.',
+      };
+    }
+  }
+
+  #checkAbort(): void {
+    if (this.controller.signal.aborted) {
+      throw this.#abortError();
+    }
+  }
+
+  #abortError(): APIUserAbortError {
+    const error = new APIUserAbortError();
+    Object.defineProperty(error, 'cause', {
+      value: this.controller.signal.reason,
+      writable: true,
+      configurable: true,
+    });
+    return error;
+  }
+
+  async #wait<T>(action: () => T | PromiseLike<T>): Promise<T> {
+    let onAbort: (() => void) | undefined;
+    // oxlint-disable-next-line promise/avoid-new -- Bridge the caller's AbortSignal while a handler or registration delay is pending.
+    const aborted = new Promise<never>((_resolve, reject) => {
+      onAbort = () => reject(this.#abortError());
+      this.controller.signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+      this.#checkAbort();
+      // Capture synchronous throws before racing cancellation, so both promises
+      // always have rejection handlers even if the callback aborts and throws.
+      const invoke = async () => await action();
+      return await Promise.race([invoke(), aborted]);
+    } finally {
+      if (onAbort) {
+        this.controller.signal.removeEventListener('abort', onAbort);
+      }
+    }
+  }
+
+  async #submit(result: ToolResult, options: RequestOptions, key = uuid4(), attempt = 0): Promise<void> {
+    this.#checkAbort();
+    try {
+      await this.#sessions.events.create(
+        this.#sessionID,
+        { events: [result], 'Idempotency-Key': key },
+        options,
+      );
+    } catch (error) {
+      const delay = [100, 300, 600][attempt];
+      if (
+        delay === undefined ||
+        !(error instanceof BadRequestError) ||
+        error.code !== 'invalid_request_error' ||
+        !error.error ||
+        !('message' in error.error) ||
+        error.error.message !== `Unknown pending tool call: ${result.call_id}`
+      ) {
+        throw error;
+      }
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        await this.#wait(
+          () =>
+            // oxlint-disable-next-line promise/avoid-new -- Own the registration timer so cancellation clears it promptly.
+            new Promise<void>((resolve) => {
+              timer = setTimeout(resolve, delay);
+            }),
+        );
+      } finally {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+        }
+      }
+      await this.#submit(result, options, key, attempt + 1);
+    }
+  }
+}

package/src/lib/agents/output-text.ts

@@ -0,0 +1,6 @@
+import type { AgentSessionMessage } from '../../resources/beta/agents/agents';
+
+/** Joins output_text blocks in content order, without filtering phase, fetching, or mutating the message. */
+export function outputText(message: AgentSessionMessage): string {
+  return message.content.map((block) => (block.type === 'output_text' ? block.text : '')).join('');
+}

package/src/lib/agents/turn-state.ts

@@ -0,0 +1,61 @@
+import type { AgentSessionEvent, AgentFunctionCallItem } from '../../resources/beta/agents/agents';
+
+/** Tracks one helper invocation's coordinator turn and duplicate deliveries.
+ * @internal
+ */
+export class TurnState {
+  #turnID: string | undefined;
+  #turnEnded = false;
+  #eventIDs = new Set<string>();
+  #calls = new Set<string>();
+
+  /** Records a delivery unless its event ID is in the bounded recent window. */
+  accept(event: AgentSessionEvent): boolean {
+    if (this.#eventIDs.has(event.event_id)) {
+      return false;
+    }
+    if (this.#eventIDs.size === 1024) {
+      const oldest = this.#eventIDs.values().next();
+      if (!oldest.done) {
+        this.#eventIDs.delete(oldest.value);
+      }
+    }
+    this.#eventIDs.add(event.event_id);
+    if (
+      event.type === 'agent.session.turn.created' &&
+      event.turn.subagent_id === null &&
+      this.#turnID === undefined
+    ) {
+      this.#turnID = event.turn_id;
+    }
+    if (
+      (event.type === 'agent.session.turn.completed' ||
+        event.type === 'agent.session.turn.failed' ||
+        event.type === 'agent.session.turn.cancelled') &&
+      this.#turnID !== undefined &&
+      event.turn_id === this.#turnID
+    ) {
+      this.#turnEnded = true;
+    }
+    return true;
+  }
+
+  /** Checks session termination after updating the selected turn state. */
+  terminal(event: AgentSessionEvent): boolean {
+    return event.type === 'agent.session.failed' || (event.type === 'agent.session.idle' && this.#turnEnded);
+  }
+
+  /** Returns each tool call once for the full invocation, including subagent turns. */
+  call(event: AgentSessionEvent): AgentFunctionCallItem | undefined {
+    if (event.type !== 'agent.session.turn.item.added' || event.item.type !== 'function_call') {
+      return;
+    }
+    const call = event.item;
+    const key = JSON.stringify([call.turn_id, call.call_id]);
+    if (this.#calls.has(key)) {
+      return;
+    }
+    this.#calls.add(key);
+    return call;
+  }
+}

package/src/lib/live/transcript-grouping.ts

@@ -15,11 +15,17 @@ export type GroupingUpdate =
   | { type: 'updated'; segment: TranscriptSegment }
   | { type: 'closed'; segment: TranscriptSegment; reason: TranscriptSegmentCloseReason };
 
+interface Acknowledgment {
+  characters: number;
+  text: string | undefined;
+}
+
 type Turn = TranscriptFragment & {
   id: string;
   previousId: string | null;
   emitted: boolean;
   canDropAsBackchannel: boolean;
+  acknowledgment?: Acknowledgment | undefined;
 };
 
 const ACKNOWLEDGMENTS = [
@@ -42,14 +48,16 @@ const ACKNOWLEDGMENTS = [
 ];
 
 function normalizeAcknowledgment(text: string): string {
-  return text
+  const normalized = text
     .toLowerCase()
     .split('-')
     .join(' ')
-    .replace(/^[\s.,!?;:"'()[\]{}]+/u, '')
-    .replace(/[\s.,!?;:"'()[\]{}]+$/u, '')
-    .split(/\s+/u)
-    .join(' ');
+    .replace(/^[\s.,!?;:"'()[\]{}]+/u, '');
+  let end = normalized.length;
+  while (end > 0 && /[\s.,!?;:"'()[\]{}]/u.test(normalized.charAt(end - 1))) {
+    end -= 1;
+  }
+  return normalized.slice(0, end).split(/\s+/u).join(' ');
 }
 
 /** The v2 grouping policy, driven by timed public text rather than engine frames. */
@@ -63,6 +71,7 @@ export class TranscriptGrouping {
   private readonly options: Required<TranscriptGrouperOptions>;
   private readonly idPrefix: string;
   private readonly acknowledgments: readonly string[];
+  private readonly maxAcknowledgmentLength: number;
 
   constructor(options: Required<TranscriptGrouperOptions>, idPrefix: string) {
     this.options = options;
@@ -71,6 +80,11 @@ export class TranscriptGrouping {
       ...ACKNOWLEDGMENTS,
       ...options.additionalAcknowledgments.map(normalizeAcknowledgment).filter(Boolean),
     ];
+    let maxLength = 0;
+    for (const acknowledgment of this.acknowledgments) {
+      maxLength = Math.max(maxLength, acknowledgment.length);
+    }
+    this.maxAcknowledgmentLength = maxLength;
   }
 
   get speaker(): TranscriptFragment['speaker'] | undefined {
@@ -183,16 +197,22 @@ export class TranscriptGrouping {
       this.buffer(fragment);
       return this.promote();
     }
+    const withinDuration =
+      fragment.endMs - (this.buffered?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs;
+    const acknowledgment = this.acknowledgment(fragment, withinDuration);
+    const normalized = withinDuration ? acknowledgment.text : undefined;
     if (separation < this.options.minTurnSeparationMs) {
-      this.buffer(fragment, this.possibleAcknowledgment(fragment));
-      return [];
-    }
-    if (this.buffered && this.standaloneAcknowledgment(fragment, this.buffered)) {
-      this.buffer(fragment, true);
+      this.buffer(
+        fragment,
+        normalized !== undefined &&
+          normalized.length > 0 &&
+          this.acknowledgments.some((phrase) => phrase.startsWith(normalized)),
+        acknowledgment,
+      );
       return [];
     }
-    if (!this.buffered && this.standaloneAcknowledgment(fragment)) {
-      this.buffer(fragment, false);
+    if (normalized !== undefined && this.acknowledgments.includes(normalized)) {
+      this.buffer(fragment, this.buffered !== undefined, acknowledgment);
       return [];
     }
     this.buffered = this.maybeDropBackchannel(undefined, fragment);
@@ -227,7 +247,7 @@ export class TranscriptGrouping {
     turn.endMs = Math.max(turn.endMs, fragment.endMs);
   }
 
-  private buffer(fragment: TranscriptFragment, canDrop?: boolean): void {
+  private buffer(fragment: TranscriptFragment, canDrop?: boolean, acknowledgment?: Acknowledgment): void {
     if (this.buffered) {
       TranscriptGrouping.append(this.buffered, fragment);
     } else {
@@ -236,6 +256,7 @@ export class TranscriptGrouping {
     if (canDrop !== undefined) {
       this.buffered.canDropAsBackchannel = canDrop;
     }
+    this.buffered.acknowledgment = acknowledgment;
   }
 
   private promote(): GroupingUpdate[] {
@@ -344,19 +365,30 @@ export class TranscriptGrouping {
     return this.buffered.canDropAsBackchannel ? undefined : this.buffered;
   }
 
-  private standaloneAcknowledgment(fragment: TranscriptFragment, previous?: Turn): boolean {
-    return (
-      fragment.endMs - (previous?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs &&
-      this.acknowledgments.includes(normalizeAcknowledgment((previous?.text ?? '') + fragment.text))
-    );
-  }
-
-  private possibleAcknowledgment(fragment: TranscriptFragment): boolean {
-    const text = normalizeAcknowledgment((this.buffered?.text ?? '') + fragment.text);
-    return (
-      fragment.endMs - (this.buffered?.startMs ?? fragment.startMs) < this.options.backchannelMaxDurationMs &&
-      text.length > 0 &&
-      this.acknowledgments.some((acknowledgment) => acknowledgment.startsWith(text))
-    );
+  private acknowledgment(fragment: TranscriptFragment, withinDuration: boolean): Acknowledgment {
+    const previous = this.buffered?.acknowledgment;
+    const previousCharacters = previous?.characters ?? 0;
+    let characters = previousCharacters;
+    const separator = /[\s.,!?;:"'()[\]{}-]/u;
+    for (
+      let index = 0;
+      index < fragment.text.length && characters <= this.maxAcknowledgmentLength;
+      index += 1
+    ) {
+      if (!separator.test(fragment.text.charAt(index))) {
+        characters += 1;
+      }
+    }
+    // Significant characters cannot disappear during normalization. Once they
+    // outgrow the configured phrases, stop counting without allocating tokens.
+    let text: string | undefined;
+    if (characters === previousCharacters && previous?.text !== undefined) {
+      // Keep the raw suffix in the turn: later text can make punctuation internal.
+      ({ text } = previous);
+    } else if (withinDuration && characters <= this.maxAcknowledgmentLength) {
+      // Retain whole-string Unicode casing (including context-sensitive sigma).
+      text = normalizeAcknowledgment((this.buffered?.text ?? '') + fragment.text);
+    }
+    return { characters, text };
   }
 }