@pipedog/core 0.0.0 → 0.2.0

package/dist/turns/user_turn_processor.js

@@ -0,0 +1,180 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_turn_processor.py
+/** Frame processor for managing the user turn lifecycle. */
+import { CancelFrame, EagerEndOfTurnCancelFrame, EndFrame, ProposedUserStartedSpeakingFrame, ProposedUserStoppedSpeakingFrame, StartFrame, UserStartedSpeakingFrame, UserStoppedSpeakingFrame, } from "../frames/frames.js";
+import { FrameDirection, FrameProcessor, } from "../processors/frame_processor.js";
+import { logger } from "../utils/logger.js";
+import { UserIdleController } from "./user_idle_controller.js";
+import { UserTurnController } from "./user_turn_controller.js";
+import { UserTurnStrategies } from "./user_turn_strategies.js";
+/**
+ * Frame processor for managing the user turn lifecycle.
+ *
+ * This processor uses a turn controller to determine when a user turn starts
+ * or stops. The actual frames emitted (e.g., UserStartedSpeakingFrame,
+ * UserStoppedSpeakingFrame) or interruptions depend on the configured
+ * strategies.
+ *
+ * Event handlers available:
+ *
+ * - on_user_turn_started: Emitted when a user turn starts.
+ * - on_user_turn_inference_triggered: Emitted when enough signal exists to
+ *   start LLM inference. Fires together with `on_user_turn_stopped` for most
+ *   strategies; fires alone when a downstream strategy gates finalization on
+ *   the LLM's verdict.
+ * - on_user_turn_stopped: Emitted when a user turn is semantically final.
+ * - on_user_turn_stop_timeout: Emitted if no stop strategy triggers before timeout.
+ * - on_user_turn_idle: Emitted when the user has been idle for the configured timeout.
+ *
+ * @example
+ * processor.eventHandler("on_user_turn_started", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_inference_triggered", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_stopped", async (processor, strategy) => { ... });
+ * processor.eventHandler("on_user_turn_stop_timeout", async (processor) => { ... });
+ * processor.eventHandler("on_user_turn_idle", async (processor) => { ... });
+ */
+export class UserTurnProcessor extends FrameProcessor {
+    _userTurnController;
+    _userIdleController;
+    constructor(options = {}) {
+        super(options);
+        this._registerEventHandler("on_user_turn_started");
+        this._registerEventHandler("on_user_turn_stopped");
+        this._registerEventHandler("on_user_turn_stop_timeout");
+        this._registerEventHandler("on_user_turn_idle");
+        this._registerEventHandler("on_user_turn_inference_triggered");
+        this._userTurnController = new UserTurnController({
+            userTurnStrategies: options.userTurnStrategies ?? new UserTurnStrategies(),
+            userTurnStopTimeout: options.userTurnStopTimeout ?? 5.0,
+        });
+        this._userTurnController.addEventHandler("on_push_frame", (_c, frame, direction) => this._onPushFrame(frame, direction));
+        this._userTurnController.addEventHandler("on_broadcast_frame", (_c, frameCls, frameOptions) => this._onBroadcastFrame(frameCls, frameOptions));
+        this._userTurnController.addEventHandler("on_user_turn_speculation_cancelled", (c) => this._onUserTurnSpeculationCancelled(c));
+        this._userTurnController.addEventHandler("on_user_turn_started", (c, strategy, params) => this._onUserTurnStarted(c, strategy, params));
+        this._userTurnController.addEventHandler("on_user_turn_stopped", (c, strategy, params) => this._onUserTurnStopped(c, strategy, params));
+        this._userTurnController.addEventHandler("on_user_turn_stop_timeout", (c) => this._onUserTurnStopTimeout(c));
+        this._userTurnController.addEventHandler("on_user_turn_inference_triggered", (c, strategy, speculation) => this._onUserTurnInferenceTriggered(c, strategy, speculation));
+        this._userIdleController = new UserIdleController({
+            userIdleTimeout: options.userIdleTimeout ?? 0,
+        });
+        this._userIdleController.addEventHandler("on_user_turn_idle", (c) => this._onUserTurnIdle(c));
+    }
+    /**
+     * Set up the processor.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    async setup(setup) {
+        await super.setup(setup);
+        await this._userTurnController.setup(setup);
+        await this._userIdleController.setup(setup);
+    }
+    /** Clean up processor resources. */
+    async cleanup() {
+        await super.cleanup();
+        await this._cleanup();
+    }
+    /**
+     * Process an incoming frame to detect user turn start or stop.
+     *
+     * The frame is passed to the user turn controller which is responsible for
+     * deciding when a user turn starts or stops and emitting the corresponding
+     * events.
+     *
+     * @param frame The frame to be processed.
+     * @param direction The direction of the incoming frame.
+     */
+    async processFrame(frame, direction) {
+        await super.processFrame(frame, direction);
+        if (frame instanceof StartFrame) {
+            await this.pushFrame(frame, direction);
+            await this._userTurnController.start();
+        }
+        else if (frame instanceof EndFrame) {
+            // Push EndFrame before stop(), because stop() waits on the task to
+            // finish and the task finishes when EndFrame is processed.
+            await this.pushFrame(frame, direction);
+            await this._stop(frame);
+        }
+        else if (frame instanceof CancelFrame) {
+            await this._cancel(frame);
+            await this.pushFrame(frame, direction);
+        }
+        else if (frame instanceof ProposedUserStartedSpeakingFrame) {
+            // A proposal is resolved once. Forwarding one our own strategies
+            // resolve would let a resolver further down the pipeline decide the
+            // same turn a second time.
+            if (!this._userTurnController.resolvesProposedTurnStartFrames) {
+                await this.pushFrame(frame, direction);
+            }
+        }
+        else if (frame instanceof ProposedUserStoppedSpeakingFrame) {
+            if (!this._userTurnController.resolvesProposedTurnStopFrames) {
+                await this.pushFrame(frame, direction);
+            }
+        }
+        else {
+            await this.pushFrame(frame, direction);
+        }
+        await this._userTurnController.processFrame(frame);
+        await this._userIdleController.processFrame(frame);
+    }
+    async _stop(_frame) {
+        await this._stopControllers();
+    }
+    async _cancel(_frame) {
+        await this._stopControllers();
+    }
+    async _stopControllers() {
+        // Session end stops the controllers' timers; what they hold may be
+        // shared, so releasing it waits for cleanup().
+        await this._userTurnController.stop();
+        await this._userIdleController.stop();
+    }
+    async _cleanup() {
+        await this._userTurnController.cleanup();
+        await this._userIdleController.cleanup();
+    }
+    async _onPushFrame(frame, direction = FrameDirection.DOWNSTREAM) {
+        await this.pushFrame(frame, direction);
+    }
+    async _onBroadcastFrame(frameCls, options) {
+        await this.broadcastFrame(frameCls, options);
+    }
+    async _onUserTurnSpeculationCancelled(_controller) {
+        await this.broadcastFrame(EagerEndOfTurnCancelFrame);
+    }
+    async _onUserTurnStarted(_controller, strategy, params) {
+        logger.debug(`${this}: User started speaking (strategy: ${strategy})`);
+        if (params.enableUserSpeakingFrames) {
+            await this.broadcastFrame(UserStartedSpeakingFrame);
+        }
+        await this._userIdleController.processFrame(new UserStartedSpeakingFrame());
+        if (params.enableInterruptions) {
+            await this.broadcastInterruption();
+        }
+        await this._callEventHandler("on_user_turn_started", strategy);
+    }
+    async _onUserTurnStopped(_controller, strategy, params) {
+        logger.debug(`${this}: User stopped speaking (strategy: ${strategy})`);
+        if (params.enableUserSpeakingFrames) {
+            await this.broadcastFrame(UserStoppedSpeakingFrame);
+        }
+        await this._userIdleController.processFrame(new UserStoppedSpeakingFrame());
+        await this._callEventHandler("on_user_turn_stopped", strategy);
+    }
+    async _onUserTurnStopTimeout(_controller) {
+        await this._callEventHandler("on_user_turn_stop_timeout");
+    }
+    async _onUserTurnIdle(_controller) {
+        await this._callEventHandler("on_user_turn_idle");
+    }
+    async _onUserTurnInferenceTriggered(_controller, strategy, _speculation) {
+        logger.debug(`${this}: User turn inference triggered (strategy: ${strategy})`);
+        await this._callEventHandler("on_user_turn_inference_triggered", strategy);
+    }
+}
+//# sourceMappingURL=user_turn_processor.js.map

package/dist/turns/user_turn_strategies.d.ts

@@ -0,0 +1,187 @@
+import { type BaseUserTurnStartStrategy } from "./user_start/index.ts";
+import { type BaseUserTurnStopStrategy, type EagerMatchPolicy } from "./user_stop/index.ts";
+import type { UserTurnCompletionConfig } from "./user_turn_completion_mixin.ts";
+/**
+ * Return the default user turn start strategies.
+ *
+ * Returns `[VADUserTurnStartStrategy, TranscriptionUserTurnStartStrategy]`.
+ * Useful when building a custom strategy list that extends the defaults.
+ *
+ * @example
+ * const startStrategies = [
+ *   new WakePhraseUserTurnStartStrategy({ phrases: ["hey pipecat"] }),
+ *   ...defaultUserTurnStartStrategies(),
+ * ];
+ */
+export declare function defaultUserTurnStartStrategies(): BaseUserTurnStartStrategy[];
+/**
+ * Return the default user turn stop strategies.
+ *
+ * Returns `[TurnAnalyzerUserTurnStopStrategy(LocalSmartTurnAnalyzerV3)]`.
+ * Useful when building a custom strategy list that extends the defaults.
+ */
+export declare function defaultUserTurnStopStrategies(): BaseUserTurnStopStrategy[];
+export interface UserTurnStrategiesOptions {
+    /**
+     * A list of user turn start strategies used to detect when the user starts
+     * speaking.
+     */
+    start?: BaseUserTurnStartStrategy[] | null;
+    /**
+     * A list of user turn stop strategies used to decide when the user stops
+     * speaking.
+     */
+    stop?: BaseUserTurnStopStrategy[] | null;
+}
+/**
+ * Container for user turn start and stop strategies.
+ *
+ * If no strategies are specified, the following defaults are used:
+ *
+ *     start: [VADUserTurnStartStrategy, TranscriptionUserTurnStartStrategy]
+ *      stop: [TurnAnalyzerUserTurnStopStrategy(LocalSmartTurnAnalyzerV3)]
+ *
+ * - `start`: A list of user turn start strategies used to detect when the
+ *   user starts speaking.
+ * - `stop`: A list of user turn stop strategies used to decide when the user
+ *   stops speaking.
+ */
+export declare class UserTurnStrategies {
+    start: BaseUserTurnStartStrategy[];
+    stop: BaseUserTurnStopStrategy[];
+    constructor(options?: UserTurnStrategiesOptions);
+    protected _postInit(): void;
+}
+export interface ExternalUserTurnStrategiesOptions extends UserTurnStrategiesOptions {
+    /**
+     * Whether to broadcast an interruption when a proposal starts a turn.
+     * Services route their `should_interrupt` setting here.
+     */
+    enableInterruptions?: boolean;
+}
+/**
+ * Container for turn strategies driven by another component in the pipeline.
+ *
+ * Preconfigures UserTurnStrategies with ExternalUserTurnStartStrategy and
+ * ExternalUserTurnStopStrategy, so a service with its own turn detection — or
+ * a shared UserTurnProcessor — controls when user turns start and stop.
+ *
+ * What the aggregator emits depends on which signal drives the turn.
+ * `ProposedUserStarted/StoppedSpeakingFrame` leaves the decision here, so the
+ * aggregator pushes the turn frames and broadcasts interruptions.
+ * `UserStarted/StoppedSpeakingFrame` means the emitter already announced the
+ * turn, so the aggregator emits nothing and the parameter below doesn't apply.
+ *
+ * - `enableInterruptions`: Whether to broadcast an interruption when a
+ *   proposal starts a turn. Services route their `should_interrupt` setting
+ *   here.
+ */
+export declare class ExternalUserTurnStrategies extends UserTurnStrategies {
+    enableInterruptions: boolean;
+    constructor(options?: ExternalUserTurnStrategiesOptions);
+    protected _postInit(): void;
+}
+export interface FilterIncompleteUserTurnStrategiesOptions extends UserTurnStrategiesOptions {
+    /**
+     * Optional configuration applied to the LLM via the
+     * `filter_incomplete_user_turns` setting. Customizes the turn-completion
+     * instructions, incomplete-turn timeouts, and re-prompts. If null, defaults
+     * from UserTurnCompletionConfig are used.
+     */
+    config?: UserTurnCompletionConfig | null;
+}
+/**
+ * Stop strategies gated on the LLM's turn-completion verdict.
+ *
+ * The LLM is asked to begin every response with one of three markers: ●
+ * (complete), ◐ (incomplete short), or ○ (incomplete long). Only ● finalizes
+ * the user turn; ◐ / ○ keep the turn open so the user can continue speaking
+ * and the LLM can re-evaluate later.
+ *
+ * Configuring strategies this way preserves the existing detector chain
+ * (defaults or user-supplied) for inference triggering and appends
+ * LLMTurnCompletionUserTurnStopStrategy as the finalizer. The detector
+ * strategies are wrapped with `deferred()` automatically so they fire only
+ * `on_user_turn_inference_triggered` and leave finalization to the LLM gate.
+ *
+ * - `config`: Optional configuration applied to the LLM via the
+ *   `filter_incomplete_user_turns` setting. Customizes the turn-completion
+ *   instructions, incomplete-turn timeouts, and re-prompts. If null, defaults
+ *   from UserTurnCompletionConfig are used.
+ *
+ * @example
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies()
+ *
+ * // Custom detector chain:
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies({
+ *   stop: [new SpeechTimeoutUserTurnStopStrategy({ ... })],
+ * })
+ *
+ * // Custom completion config:
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies({
+ *   config: new UserTurnCompletionConfig({
+ *     incompleteShortTimeout: 5.0,
+ *     incompleteLongTimeout: 10.0,
+ *   }),
+ * })
+ */
+export declare class FilterIncompleteUserTurnStrategies extends UserTurnStrategies {
+    config: UserTurnCompletionConfig | null;
+    constructor(options?: FilterIncompleteUserTurnStrategiesOptions);
+    protected _postInit(): void;
+}
+export interface EagerUserTurnStrategiesOptions extends ExternalUserTurnStrategiesOptions {
+    /**
+     * Decides whether the committed transcript is close enough to the eager one
+     * to keep the speculative response. Defaults to NormalizedMatch.
+     */
+    matchPolicy?: EagerMatchPolicy | null;
+    /**
+     * Seconds a prediction may go unresolved before it is withdrawn and the
+     * turn falls back to answering the committed transcript.
+     */
+    speculationTimeout?: number;
+}
+/**
+ * Strategies for a service that predicts the end of a turn before committing.
+ *
+ * Answers the prediction while the turn is still open, so the gap before the
+ * committed end of turn is spent generating a response instead of waiting for
+ * one. The response is discarded if the user resumes speaking or the
+ * committed transcript differs from the eager one. See
+ * EagerUserTurnStopStrategy.
+ *
+ * The response is held by the LLM service until the turn is confirmed, so no
+ * extra processor is needed in the pipeline.
+ *
+ * The service owns turn detection here, so this replaces the detector chain
+ * rather than extending it: a local detector running alongside would trigger
+ * a second inference for the same turn.
+ *
+ * - `matchPolicy`: Decides whether the committed transcript is close enough to
+ *   the eager one to keep the speculative response. Defaults to
+ *   NormalizedMatch, since services commonly format the transcript they
+ *   commit (capitalization, punctuation) while leaving the eager one raw. Pass
+ *   ExactMatch to require the two to be identical.
+ * - `speculationTimeout`: Seconds a prediction may go unresolved before it is
+ *   withdrawn and the turn falls back to answering the committed transcript.
+ *   Guards against a service that stops sending turn signals
+ *   mid-speculation, which would otherwise leave the response held and the
+ *   bot silent.
+ * - `enableInterruptions`: Whether to broadcast an interruption when a
+ *   proposal starts a turn. Services route their `should_interrupt` setting
+ *   here.
+ *
+ * @example
+ * userTurnStrategies: new EagerUserTurnStrategies()
+ *
+ * // Require the committed transcript to match the eager one exactly:
+ * userTurnStrategies: new EagerUserTurnStrategies({ matchPolicy: new ExactMatch() })
+ */
+export declare class EagerUserTurnStrategies extends ExternalUserTurnStrategies {
+    matchPolicy: EagerMatchPolicy | null;
+    speculationTimeout: number;
+    constructor(options?: EagerUserTurnStrategiesOptions);
+    protected _postInit(): void;
+}
+//# sourceMappingURL=user_turn_strategies.d.ts.map

package/dist/turns/user_turn_strategies.js

@@ -0,0 +1,222 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_turn_strategies.py
+/** Turn start strategy configuration. */
+import { LocalSmartTurnAnalyzerV3 } from "../audio/turn/smart_turn/local_smart_turn_v3.js";
+import { ExternalUserTurnStartStrategy, TranscriptionUserTurnStartStrategy, VADUserTurnStartStrategy, } from "./user_start/index.js";
+import { deferred, EagerUserTurnStopStrategy, ExternalUserTurnStopStrategy, LLMTurnCompletionUserTurnStopStrategy, TurnAnalyzerUserTurnStopStrategy, } from "./user_stop/index.js";
+/**
+ * Return the default user turn start strategies.
+ *
+ * Returns `[VADUserTurnStartStrategy, TranscriptionUserTurnStartStrategy]`.
+ * Useful when building a custom strategy list that extends the defaults.
+ *
+ * @example
+ * const startStrategies = [
+ *   new WakePhraseUserTurnStartStrategy({ phrases: ["hey pipecat"] }),
+ *   ...defaultUserTurnStartStrategies(),
+ * ];
+ */
+export function defaultUserTurnStartStrategies() {
+    return [new VADUserTurnStartStrategy(), new TranscriptionUserTurnStartStrategy()];
+}
+/**
+ * Return the default user turn stop strategies.
+ *
+ * Returns `[TurnAnalyzerUserTurnStopStrategy(LocalSmartTurnAnalyzerV3)]`.
+ * Useful when building a custom strategy list that extends the defaults.
+ */
+export function defaultUserTurnStopStrategies() {
+    return [new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer: new LocalSmartTurnAnalyzerV3() })];
+}
+// Python dataclasses run `__post_init__` once, after every field of the most
+// derived class is set. Each constructor below assigns its own fields and then
+// runs `_postInit()` only when it is the most derived of these dataclasses in
+// `new.target`'s chain, so the override chain behaves like upstream's (a user
+// subclass that adds no dataclass fields gets it from its nearest parent).
+const postInitClasses = new Set();
+function runsPostInit(target, cls) {
+    let proto = target;
+    while (proto && !postInitClasses.has(proto)) {
+        proto = Object.getPrototypeOf(proto);
+    }
+    return proto === cls;
+}
+/**
+ * Container for user turn start and stop strategies.
+ *
+ * If no strategies are specified, the following defaults are used:
+ *
+ *     start: [VADUserTurnStartStrategy, TranscriptionUserTurnStartStrategy]
+ *      stop: [TurnAnalyzerUserTurnStopStrategy(LocalSmartTurnAnalyzerV3)]
+ *
+ * - `start`: A list of user turn start strategies used to detect when the
+ *   user starts speaking.
+ * - `stop`: A list of user turn stop strategies used to decide when the user
+ *   stops speaking.
+ */
+export class UserTurnStrategies {
+    start;
+    stop;
+    constructor(options = {}) {
+        this.start = options.start ?? [];
+        this.stop = options.stop ?? [];
+        if (runsPostInit(new.target, UserTurnStrategies))
+            this._postInit();
+    }
+    _postInit() {
+        if (!this.start || this.start.length === 0) {
+            this.start = defaultUserTurnStartStrategies();
+        }
+        if (!this.stop || this.stop.length === 0) {
+            this.stop = defaultUserTurnStopStrategies();
+        }
+    }
+}
+/**
+ * Container for turn strategies driven by another component in the pipeline.
+ *
+ * Preconfigures UserTurnStrategies with ExternalUserTurnStartStrategy and
+ * ExternalUserTurnStopStrategy, so a service with its own turn detection — or
+ * a shared UserTurnProcessor — controls when user turns start and stop.
+ *
+ * What the aggregator emits depends on which signal drives the turn.
+ * `ProposedUserStarted/StoppedSpeakingFrame` leaves the decision here, so the
+ * aggregator pushes the turn frames and broadcasts interruptions.
+ * `UserStarted/StoppedSpeakingFrame` means the emitter already announced the
+ * turn, so the aggregator emits nothing and the parameter below doesn't apply.
+ *
+ * - `enableInterruptions`: Whether to broadcast an interruption when a
+ *   proposal starts a turn. Services route their `should_interrupt` setting
+ *   here.
+ */
+export class ExternalUserTurnStrategies extends UserTurnStrategies {
+    enableInterruptions;
+    constructor(options = {}) {
+        super(options);
+        this.enableInterruptions = options.enableInterruptions ?? true;
+        if (runsPostInit(new.target, ExternalUserTurnStrategies))
+            this._postInit();
+    }
+    _postInit() {
+        this.start = [
+            new ExternalUserTurnStartStrategy({ enableInterruptions: this.enableInterruptions }),
+        ];
+        this.stop = [new ExternalUserTurnStopStrategy()];
+    }
+}
+/**
+ * Stop strategies gated on the LLM's turn-completion verdict.
+ *
+ * The LLM is asked to begin every response with one of three markers: ●
+ * (complete), ◐ (incomplete short), or ○ (incomplete long). Only ● finalizes
+ * the user turn; ◐ / ○ keep the turn open so the user can continue speaking
+ * and the LLM can re-evaluate later.
+ *
+ * Configuring strategies this way preserves the existing detector chain
+ * (defaults or user-supplied) for inference triggering and appends
+ * LLMTurnCompletionUserTurnStopStrategy as the finalizer. The detector
+ * strategies are wrapped with `deferred()` automatically so they fire only
+ * `on_user_turn_inference_triggered` and leave finalization to the LLM gate.
+ *
+ * - `config`: Optional configuration applied to the LLM via the
+ *   `filter_incomplete_user_turns` setting. Customizes the turn-completion
+ *   instructions, incomplete-turn timeouts, and re-prompts. If null, defaults
+ *   from UserTurnCompletionConfig are used.
+ *
+ * @example
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies()
+ *
+ * // Custom detector chain:
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies({
+ *   stop: [new SpeechTimeoutUserTurnStopStrategy({ ... })],
+ * })
+ *
+ * // Custom completion config:
+ * userTurnStrategies: new FilterIncompleteUserTurnStrategies({
+ *   config: new UserTurnCompletionConfig({
+ *     incompleteShortTimeout: 5.0,
+ *     incompleteLongTimeout: 10.0,
+ *   }),
+ * })
+ */
+export class FilterIncompleteUserTurnStrategies extends UserTurnStrategies {
+    config;
+    constructor(options = {}) {
+        super(options);
+        this.config = options.config ?? null;
+        if (runsPostInit(new.target, FilterIncompleteUserTurnStrategies))
+            this._postInit();
+    }
+    _postInit() {
+        super._postInit();
+        // Defer the detector chain so it only fires inference-triggered, then
+        // append the LLM gate as the sole finalizer.
+        const gated = (this.stop ?? []).map((s) => deferred(s));
+        gated.push(new LLMTurnCompletionUserTurnStopStrategy({ config: this.config }));
+        this.stop = gated;
+    }
+}
+/**
+ * Strategies for a service that predicts the end of a turn before committing.
+ *
+ * Answers the prediction while the turn is still open, so the gap before the
+ * committed end of turn is spent generating a response instead of waiting for
+ * one. The response is discarded if the user resumes speaking or the
+ * committed transcript differs from the eager one. See
+ * EagerUserTurnStopStrategy.
+ *
+ * The response is held by the LLM service until the turn is confirmed, so no
+ * extra processor is needed in the pipeline.
+ *
+ * The service owns turn detection here, so this replaces the detector chain
+ * rather than extending it: a local detector running alongside would trigger
+ * a second inference for the same turn.
+ *
+ * - `matchPolicy`: Decides whether the committed transcript is close enough to
+ *   the eager one to keep the speculative response. Defaults to
+ *   NormalizedMatch, since services commonly format the transcript they
+ *   commit (capitalization, punctuation) while leaving the eager one raw. Pass
+ *   ExactMatch to require the two to be identical.
+ * - `speculationTimeout`: Seconds a prediction may go unresolved before it is
+ *   withdrawn and the turn falls back to answering the committed transcript.
+ *   Guards against a service that stops sending turn signals
+ *   mid-speculation, which would otherwise leave the response held and the
+ *   bot silent.
+ * - `enableInterruptions`: Whether to broadcast an interruption when a
+ *   proposal starts a turn. Services route their `should_interrupt` setting
+ *   here.
+ *
+ * @example
+ * userTurnStrategies: new EagerUserTurnStrategies()
+ *
+ * // Require the committed transcript to match the eager one exactly:
+ * userTurnStrategies: new EagerUserTurnStrategies({ matchPolicy: new ExactMatch() })
+ */
+export class EagerUserTurnStrategies extends ExternalUserTurnStrategies {
+    matchPolicy;
+    speculationTimeout;
+    constructor(options = {}) {
+        super(options);
+        this.matchPolicy = options.matchPolicy ?? null;
+        this.speculationTimeout = options.speculationTimeout ?? 5.0;
+        if (runsPostInit(new.target, EagerUserTurnStrategies))
+            this._postInit();
+    }
+    _postInit() {
+        super._postInit();
+        this.stop = [
+            new EagerUserTurnStopStrategy({
+                matchPolicy: this.matchPolicy,
+                speculationTimeout: this.speculationTimeout,
+            }),
+        ];
+    }
+}
+postInitClasses.add(UserTurnStrategies);
+postInitClasses.add(ExternalUserTurnStrategies);
+postInitClasses.add(FilterIncompleteUserTurnStrategies);
+postInitClasses.add(EagerUserTurnStrategies);
+//# sourceMappingURL=user_turn_strategies.js.map

package/dist/utils/async_tool_cancellation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Constants for the built-in async tool cancellation feature.
+ *
+ * A function registered with `cancellableByLlm: true` is advertised alongside
+ * a cancel tool named for it, built here, and the instructions below are
+ * composed into the system instruction — so the LLM can drop work whose result
+ * is no longer wanted. A tool that doesn't opt in has no cancel tool at all.
+ *
+ * A single running call is stopped without arguments. Telling several calls of
+ * one tool apart takes the `tool_call_id` the conversation already carries, on
+ * the message that reported each call running.
+ */
+import { FunctionSchema } from "../adapters/schemas/function_schema.ts";
+export declare const ASYNC_TOOL_CANCELLATION_INSTRUCTIONS = "ASYNC TOOL CANCELLATION:\nSome of your tools keep running in the background after you have replied, and some of those can be stopped early.\n\nWork that can be stopped early has its own cancel tool, named for it: a running write_report call is stopped by cancel_write_report. Work with no such tool cannot be stopped and will finish on its own.\n\nWhen the user no longer wants a result you are still waiting on, call the corresponding cancel tool. Only the call stops the work: saying you cancelled it, or that you'll skip it, leaves it running and its result will still arrive and contradict you. So when the same turn also asks for something else, make the call and answer \u2014 don't just answer.\n\nCall the cancel tool with no arguments and it stops the one call that is running. If several calls of that same tool are running, it needs a tool_call_id to say which. Each call's id is already in the conversation: find the tool message that reported it running, which carries \"status\": \"running\", its \"tool_call_id\", and the arguments that call was given. Copy that id exactly as written; never invent or guess one.";
+export declare const CANCEL_TOOL_PREFIX = "cancel_";
+/**
+ * Name of the tool that cancels calls of `functionName`.
+ *
+ * @param functionName The cancellable tool.
+ * @returns The built-in cancel tool's name, e.g. `cancel_write_report`.
+ */
+export declare function cancelToolName(functionName: string): string;
+/**
+ * Build the cancel tool for one cancellable tool.
+ *
+ * Which work to stop is carried by the tool the model picks, so a single
+ * running call is stopped without arguments. `tool_call_id` only has to be
+ * given to choose between several calls of the same tool, and the handler
+ * refuses with the ids when it is needed and missing.
+ *
+ * @param functionName The tool whose calls this one cancels.
+ * @returns The schema to advertise alongside `functionName`.
+ */
+export declare function buildCancelToolSchema(functionName: string): FunctionSchema;
+//# sourceMappingURL=async_tool_cancellation.d.ts.map