@pipedog/core 0.0.0 → 0.2.0

package/dist/turns/user_start/wake_phrase_user_turn_start_strategy.js

@@ -0,0 +1,238 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_start/wake_phrase_user_turn_start_strategy.py
+/** User turn start strategy that gates interaction behind wake phrase detection. */
+import { Event, TimeoutError, waitFor } from "@pipedog/asyncio";
+import { BotSpeakingFrame, TranscriptionFrame, UserSpeakingFrame, VADUserStartedSpeakingFrame, } from "../../frames/frames.js";
+import { logger } from "../../utils/logger.js";
+import { ProcessFrameResult } from "../types.js";
+import { BaseUserTurnStartStrategy, } from "./base_user_turn_start_strategy.js";
+/** Internal state for wake phrase detection. */
+export const _WakeState = {
+    IDLE: "idle",
+    AWAKE: "awake",
+};
+// Python's `\w` is Unicode-aware; JS's is ASCII-only even with the `u` flag.
+const WORD_CHAR = "[\\p{L}\\p{N}\\p{M}_]";
+const NON_WORD_NON_SPACE = /[^\p{L}\p{N}\p{M}_\s]/gu;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\/-]/g, "\\$&");
+}
+/**
+ * User turn start strategy that requires a wake phrase before interaction.
+ *
+ * Blocks subsequent strategies until a wake phrase is detected in a final
+ * transcription. After detection, allows interaction for a configurable
+ * timeout period before requiring the wake phrase again. Use
+ * `singleActivation: true` to require the wake phrase before every turn.
+ *
+ * This strategy should be placed first in the start strategies list.
+ *
+ * Event handlers available:
+ *
+ * - on_wake_phrase_detected: Called when a wake phrase is matched.
+ * - on_wake_phrase_timeout: Called when the inactivity timeout expires
+ *   (timeout mode only).
+ *
+ * @example
+ * // Timeout mode (default): wake phrase unlocks interaction for 10s
+ * const strategy = new WakePhraseUserTurnStartStrategy({
+ *   phrases: ["hey pipecat", "ok pipecat"],
+ *   timeout: 10.0,
+ * });
+ *
+ * // Single activation: wake phrase required before every turn
+ * const single = new WakePhraseUserTurnStartStrategy({
+ *   phrases: ["hey pipecat"],
+ *   singleActivation: true,
+ * });
+ *
+ * strategy.eventHandler("on_wake_phrase_detected", async (strategy, phrase) => { ... });
+ * strategy.eventHandler("on_wake_phrase_timeout", async (strategy) => { ... });
+ *
+ * `timeout`: In timeout mode, the timer resets on activity (user, bot speech).
+ * In single activation mode, acts as a keepalive window — the strategy stays
+ * AWAKE for this duration after wake phrase detection, allowing the current
+ * turn to complete before returning to IDLE.
+ */
+export class WakePhraseUserTurnStartStrategy extends BaseUserTurnStartStrategy {
+    _phrases;
+    _timeout;
+    _singleActivation;
+    _patterns = [];
+    _state = _WakeState.IDLE;
+    _accumulatedText = "";
+    _timeoutEvent = new Event();
+    _timeoutTask = null;
+    constructor(options) {
+        super(options);
+        this._phrases = options.phrases;
+        this._timeout = options.timeout ?? 10.0;
+        this._singleActivation = options.singleActivation ?? false;
+        for (const phrase of this._phrases) {
+            const words = phrase.split(/\s+/).filter((word) => word.length > 0);
+            const pattern = new RegExp(`(?<!${WORD_CHAR})${words.map(escapeRegExp).join("\\s*")}(?!${WORD_CHAR})`, "iu");
+            this._patterns.push(pattern);
+        }
+        this._registerEventHandler("on_wake_phrase_detected");
+        this._registerEventHandler("on_wake_phrase_timeout");
+    }
+    /** Returns the current wake state. */
+    get state() {
+        return this._state;
+    }
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    async setup(setup) {
+        await super.setup(setup);
+        if (!this._timeoutTask) {
+            this._timeoutTask = this.taskManager.createTask(() => this._timeoutTaskHandler(), `${this}::_timeout_task_handler`);
+        }
+    }
+    /** Cleanup the strategy. */
+    async cleanup() {
+        await super.cleanup();
+        if (this._timeoutTask) {
+            await this.taskManager.cancelTask(this._timeoutTask);
+            this._timeoutTask = null;
+        }
+    }
+    /**
+     * Ready the strategy for a new user turn.
+     *
+     * In timeout mode, preserves state and refreshes the timeout — a turn
+     * starting is the activity that keeps the strategy awake. In single
+     * activation mode, does nothing: the keepalive timeout (started when the
+     * wake phrase was detected) handles the transition back to IDLE.
+     */
+    async handleUserTurnStarted() {
+        if (this._state === _WakeState.AWAKE) {
+            if (!this._singleActivation) {
+                this._refreshTimeout();
+            }
+        }
+    }
+    /**
+     * Process an incoming frame for wake phrase detection or passthrough.
+     *
+     * @param frame The frame to be processed.
+     * @returns STOP when the wake phrase is detected or when in IDLE state
+     *   (blocks subsequent strategies), CONTINUE when in AWAKE state (allows
+     *   subsequent strategies to proceed).
+     */
+    async processFrame(frame) {
+        await super.processFrame(frame);
+        if (this._state === _WakeState.IDLE) {
+            return await this._processIdle(frame);
+        }
+        return await this._processAwake(frame);
+    }
+    /**
+     * Process a frame while in IDLE state.
+     *
+     * Only final `TranscriptionFrame` instances are checked for wake phrase
+     * matches. When a match is found, a user turn start is triggered.
+     * Transcription frames that don't match have their text cleared so that
+     * pre-wake-phrase speech is not added to the LLM context. All frames
+     * return STOP to block subsequent strategies.
+     */
+    async _processIdle(frame) {
+        if (frame instanceof TranscriptionFrame) {
+            if (this._checkWakePhrase(frame.text)) {
+                await this.triggerUserTurnStarted();
+                return ProcessFrameResult.STOP;
+            }
+            await this.triggerResetAggregation();
+        }
+        return ProcessFrameResult.STOP;
+    }
+    /**
+     * Process a frame while in AWAKE state.
+     *
+     * Refreshes the timeout on activity frames (timeout mode only). Returns
+     * CONTINUE so subsequent strategies can process the frame.
+     */
+    async _processAwake(frame) {
+        if (!this._singleActivation) {
+            if (frame instanceof UserSpeakingFrame || frame instanceof BotSpeakingFrame) {
+                this._refreshTimeout();
+            }
+            else if (frame instanceof TranscriptionFrame) {
+                this._refreshTimeout();
+            }
+            else if (frame instanceof VADUserStartedSpeakingFrame) {
+                this._refreshTimeout();
+            }
+        }
+        return ProcessFrameResult.CONTINUE;
+    }
+    /** Strip punctuation from text, keeping only letters, digits, and whitespace. */
+    static _stripPunctuation(text) {
+        return text.replace(NON_WORD_NON_SPACE, "");
+    }
+    /**
+     * Check if the accumulated text contains a wake phrase.
+     *
+     * Punctuation is stripped before matching so that STT output like
+     * "Hey, Pipecat!" still matches the phrase "hey pipecat".
+     *
+     * @param text New transcription text to append and check.
+     * @returns True if a wake phrase was found, false otherwise.
+     */
+    _checkWakePhrase(text) {
+        this._accumulatedText += ` ${WakePhraseUserTurnStartStrategy._stripPunctuation(text)}`;
+        // Cap accumulated text to prevent unbounded growth.
+        if (this._accumulatedText.length > 250) {
+            this._accumulatedText = this._accumulatedText.slice(-250);
+        }
+        for (const [i, pattern] of this._patterns.entries()) {
+            if (pattern.test(this._accumulatedText)) {
+                const phrase = this._phrases[i];
+                logger.debug(`${this} wake phrase detected: '${phrase}'`);
+                this._transitionToAwake(phrase);
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Transition from IDLE to AWAKE state. */
+    _transitionToAwake(phrase) {
+        this._state = _WakeState.AWAKE;
+        this._accumulatedText = "";
+        this._refreshTimeout();
+        this.taskManager.createTask(() => this._callEventHandler("on_wake_phrase_detected", phrase), `${this}::on_wake_phrase_detected`);
+    }
+    /** Transition from AWAKE to IDLE state. */
+    _transitionToIdle() {
+        logger.debug(`${this} wake phrase timeout, returning to IDLE`);
+        this._state = _WakeState.IDLE;
+        this._accumulatedText = "";
+        this.taskManager.createTask(() => this._callEventHandler("on_wake_phrase_timeout"), `${this}::on_wake_phrase_timeout`);
+    }
+    /** Refresh the inactivity timeout. */
+    _refreshTimeout() {
+        this._timeoutEvent.set();
+    }
+    /** Background task that monitors inactivity timeout. */
+    async _timeoutTaskHandler() {
+        while (true) {
+            try {
+                await waitFor(() => this._timeoutEvent.wait(), this._timeout);
+                this._timeoutEvent.clear();
+            }
+            catch (e) {
+                if (!(e instanceof TimeoutError))
+                    throw e;
+                if (this._state === _WakeState.AWAKE) {
+                    this._transitionToIdle();
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=wake_phrase_user_turn_start_strategy.js.map

package/dist/turns/user_stop/base_user_turn_stop_strategy.d.ts

@@ -0,0 +1,174 @@
+/** Base user turn stop strategy for determining when the user stopped speaking. */
+import type { Frame } from "../../frames/frames.ts";
+import { FrameDirection, type FrameProcessorSetup } from "../../processors/frame_processor.ts";
+import { BaseObject, type BaseObjectOptions } from "../../utils/base_object.ts";
+import type { ProcessFrameResult, UserTurnSpeculation } from "../types.ts";
+export interface UserTurnStoppedParamsOptions {
+    /**
+     * Whether to emit `UserStoppedSpeakingFrame` for this turn. False when the
+     * turn end was already announced elsewhere — by a shared
+     * `UserTurnProcessor`, or by a service that emits turn frames rather than
+     * proposing them.
+     */
+    enableUserSpeakingFrames: boolean;
+    /**
+     * Whether this turn end confirms a speculative response that was already
+     * generated. The aggregator then writes the turn to the context without
+     * running inference again, since the answer is already on its way.
+     */
+    confirmsSpeculation?: boolean;
+}
+/**
+ * Parameters emitted when a user turn stops.
+ *
+ * These parameters are passed to the `on_user_turn_stopped` event and provide
+ * contextual information about how the end of user turn should be handled by
+ * the user aggregator.
+ *
+ * - `enableUserSpeakingFrames`: Whether to emit `UserStoppedSpeakingFrame`
+ *   for this turn. False when the turn end was already announced elsewhere.
+ * - `confirmsSpeculation`: Whether this turn end confirms a speculative
+ *   response that was already generated.
+ */
+export declare class UserTurnStoppedParams {
+    enableUserSpeakingFrames: boolean;
+    confirmsSpeculation: boolean;
+    constructor(options: UserTurnStoppedParamsOptions);
+}
+export interface BaseUserTurnStopStrategyOptions extends BaseObjectOptions {
+}
+export interface TriggerUserTurnStoppedOptions {
+    /**
+     * Whether to emit `UserStoppedSpeakingFrame` for this turn. Pass false when
+     * something else in the pipeline has already emitted it.
+     */
+    enableUserSpeakingFrames?: boolean | null;
+}
+export interface TriggerUserTurnInferenceTriggeredOptions {
+    /**
+     * Set to run this inference speculatively, against a provisional context
+     * carrying the turn text it names, for a turn that hasn't ended yet. The
+     * response it produces is held back until the turn is confirmed. Leave null
+     * to run the inference against the conversation as it stands.
+     */
+    speculation?: UserTurnSpeculation | null;
+}
+export interface TriggerUserTurnFinalizedOptions extends TriggerUserTurnStoppedOptions {
+    /**
+     * Whether a response generated ahead of this turn ending already answers
+     * it, so inference should not run again.
+     */
+    confirmsSpeculation?: boolean;
+}
+/**
+ * Base class for strategies that determine when the user stops speaking.
+ *
+ * Subclasses should implement logic to detect when the user stops
+ * speaking. This could be based on analyzing incoming frames (such as
+ * transcriptions), conversation state, or other heuristics.
+ *
+ * Events triggered by strategies:
+ *
+ *   - `on_push_frame`: Indicates the strategy wants to push a frame.
+ *   - `on_user_turn_inference_triggered`: Signals that enough evidence
+ *     exists to start LLM inference for the current user turn, carrying a
+ *     `UserTurnSpeculation` when the turn it answers hasn't ended yet. In
+ *     most cases this fires together with `on_user_turn_stopped`. Strategies
+ *     that gate finalization on the LLM (e.g.
+ *     `LLMTurnCompletionUserTurnStopStrategy`) fire only this event
+ *     upstream and a separate strategy fires `on_user_turn_stopped` once
+ *     the LLM confirms the turn is complete.
+ *   - `on_user_turn_stopped`: Signals that the user turn is semantically
+ *     final. Observers, transcript appenders, and UI indicators should
+ *     bind this event.
+ *
+ * Porting note: the deprecated `enable_user_speaking_frames` constructor
+ * argument and the deprecated `reset()` hook are not ported.
+ */
+export declare class BaseUserTurnStopStrategy extends BaseObject {
+    protected _enableUserSpeakingFrames: boolean;
+    constructor(options?: BaseUserTurnStopStrategyOptions);
+    /**
+     * Whether this strategy resolves proposals into turn stops.
+     *
+     * A `ProposedUserStoppedSpeakingFrame` is a request for a decision, so a
+     * strategy that acts on one consumes it: the frame stops travelling, and no
+     * resolver further along decides the same turn a second time. Override to
+     * true in a strategy that handles that frame — including one that holds the
+     * proposal for a while before deciding.
+     */
+    get resolvesProposedTurnStopFrames(): boolean;
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Cleanup the strategy. */
+    cleanup(): Promise<void>;
+    /**
+     * Notify the strategy that a user turn has started.
+     *
+     * The controller calls this on every stop strategy when a turn begins.
+     * Override to run, for example, logic to arm the strategy to detect the
+     * end of the turn now in progress.
+     */
+    handleUserTurnStarted(): Promise<void>;
+    /**
+     * Notify the strategy that the user turn has stopped.
+     *
+     * The controller calls this on every stop strategy when a turn ends,
+     * regardless of which strategy (or the stop watchdog timeout) ended it.
+     * Override to run stop-specific logic — e.g. dropping a turn analyzer's
+     * buffered speech that must not survive an externally-ended turn.
+     */
+    handleUserTurnStopped(): Promise<void>;
+    /**
+     * Process an incoming frame to decide whether the user stopped speaking.
+     *
+     * Subclasses should override this to implement logic that decides whether
+     * the user has stopped speaking.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns A ProcessFrameResult indicating the outcome, or null (treated as
+     *   CONTINUE for backward compatibility).
+     */
+    processFrame(_frame: Frame): Promise<ProcessFrameResult | null>;
+    /**
+     * Emit on_push_frame to push a frame using the user aggregator.
+     *
+     * @param frame The frame to be pushed.
+     * @param direction What direction the frame should be pushed to.
+     */
+    pushFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Emit on_broadcast_frame to broadcast a frame using the user aggregator.
+     *
+     * @param frameCls The class of the frame to be broadcasted.
+     * @param options Options to be passed to the frame's constructor.
+     */
+    broadcastFrame<O>(frameCls: new (options: O) => Frame, options?: O): Promise<void>;
+    /**
+     * Withdraw the speculation this strategy has in flight.
+     *
+     * Emitted rather than pushed so the host broadcasts it the same way it
+     * broadcasts the turn end. A withdrawal that took the queued path would
+     * reach a downstream gate *after* the turn end that follows it, and the
+     * gate would release the response the withdrawal was meant to discard.
+     */
+    triggerUserTurnSpeculationCancelled(): Promise<void>;
+    /**
+     * Fire both `on_user_turn_inference_triggered` and `on_user_turn_stopped`.
+     *
+     * Most strategies call this when they decide a turn has ended. To
+     * defer finalization to another strategy (so this strategy fires
+     * only the inference-triggered event), wrap this strategy with
+     * `deferred()` instead of changing the trigger call.
+     */
+    triggerUserTurnStopped(options?: TriggerUserTurnStoppedOptions): Promise<void>;
+    /** Trigger only the `on_user_turn_inference_triggered` event. */
+    triggerUserTurnInferenceTriggered(options?: TriggerUserTurnInferenceTriggeredOptions): Promise<void>;
+    /** Trigger only the `on_user_turn_stopped` event. */
+    triggerUserTurnFinalized(options?: TriggerUserTurnFinalizedOptions): Promise<void>;
+}
+//# sourceMappingURL=base_user_turn_stop_strategy.d.ts.map

package/dist/turns/user_stop/base_user_turn_stop_strategy.js

@@ -0,0 +1,170 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/turns/user_stop/base_user_turn_stop_strategy.py
+import { FrameDirection } from "../../processors/frame_processor.js";
+import { BaseObject } from "../../utils/base_object.js";
+/**
+ * Parameters emitted when a user turn stops.
+ *
+ * These parameters are passed to the `on_user_turn_stopped` event and provide
+ * contextual information about how the end of user turn should be handled by
+ * the user aggregator.
+ *
+ * - `enableUserSpeakingFrames`: Whether to emit `UserStoppedSpeakingFrame`
+ *   for this turn. False when the turn end was already announced elsewhere.
+ * - `confirmsSpeculation`: Whether this turn end confirms a speculative
+ *   response that was already generated.
+ */
+export class UserTurnStoppedParams {
+    enableUserSpeakingFrames;
+    confirmsSpeculation;
+    constructor(options) {
+        this.enableUserSpeakingFrames = options.enableUserSpeakingFrames;
+        this.confirmsSpeculation = options.confirmsSpeculation ?? false;
+    }
+}
+/**
+ * Base class for strategies that determine when the user stops speaking.
+ *
+ * Subclasses should implement logic to detect when the user stops
+ * speaking. This could be based on analyzing incoming frames (such as
+ * transcriptions), conversation state, or other heuristics.
+ *
+ * Events triggered by strategies:
+ *
+ *   - `on_push_frame`: Indicates the strategy wants to push a frame.
+ *   - `on_user_turn_inference_triggered`: Signals that enough evidence
+ *     exists to start LLM inference for the current user turn, carrying a
+ *     `UserTurnSpeculation` when the turn it answers hasn't ended yet. In
+ *     most cases this fires together with `on_user_turn_stopped`. Strategies
+ *     that gate finalization on the LLM (e.g.
+ *     `LLMTurnCompletionUserTurnStopStrategy`) fire only this event
+ *     upstream and a separate strategy fires `on_user_turn_stopped` once
+ *     the LLM confirms the turn is complete.
+ *   - `on_user_turn_stopped`: Signals that the user turn is semantically
+ *     final. Observers, transcript appenders, and UI indicators should
+ *     bind this event.
+ *
+ * Porting note: the deprecated `enable_user_speaking_frames` constructor
+ * argument and the deprecated `reset()` hook are not ported.
+ */
+export class BaseUserTurnStopStrategy extends BaseObject {
+    _enableUserSpeakingFrames = true;
+    constructor(options = {}) {
+        super(options);
+        this._registerEventHandler("on_push_frame", true);
+        this._registerEventHandler("on_broadcast_frame", true);
+        this._registerEventHandler("on_user_turn_inference_triggered", true);
+        this._registerEventHandler("on_user_turn_speculation_cancelled", true);
+        this._registerEventHandler("on_user_turn_stopped", true);
+    }
+    /**
+     * Whether this strategy resolves proposals into turn stops.
+     *
+     * A `ProposedUserStoppedSpeakingFrame` is a request for a decision, so a
+     * strategy that acts on one consumes it: the frame stops travelling, and no
+     * resolver further along decides the same turn a second time. Override to
+     * true in a strategy that handles that frame — including one that holds the
+     * proposal for a while before deciding.
+     */
+    get resolvesProposedTurnStopFrames() {
+        return false;
+    }
+    /**
+     * Set up the strategy.
+     *
+     * @param setup Configuration object containing setup parameters.
+     */
+    async setup(setup) {
+        await super.setup(setup.taskManager);
+    }
+    /** Cleanup the strategy. */
+    async cleanup() { }
+    /**
+     * Notify the strategy that a user turn has started.
+     *
+     * The controller calls this on every stop strategy when a turn begins.
+     * Override to run, for example, logic to arm the strategy to detect the
+     * end of the turn now in progress.
+     */
+    async handleUserTurnStarted() { }
+    /**
+     * Notify the strategy that the user turn has stopped.
+     *
+     * The controller calls this on every stop strategy when a turn ends,
+     * regardless of which strategy (or the stop watchdog timeout) ended it.
+     * Override to run stop-specific logic — e.g. dropping a turn analyzer's
+     * buffered speech that must not survive an externally-ended turn.
+     */
+    async handleUserTurnStopped() { }
+    /**
+     * Process an incoming frame to decide whether the user stopped speaking.
+     *
+     * Subclasses should override this to implement logic that decides whether
+     * the user has stopped speaking.
+     *
+     * @param frame The frame to be analyzed.
+     * @returns A ProcessFrameResult indicating the outcome, or null (treated as
+     *   CONTINUE for backward compatibility).
+     */
+    async processFrame(_frame) {
+        return null;
+    }
+    /**
+     * Emit on_push_frame to push a frame using the user aggregator.
+     *
+     * @param frame The frame to be pushed.
+     * @param direction What direction the frame should be pushed to.
+     */
+    async pushFrame(frame, direction = FrameDirection.DOWNSTREAM) {
+        await this._callEventHandler("on_push_frame", frame, direction);
+    }
+    /**
+     * Emit on_broadcast_frame to broadcast a frame using the user aggregator.
+     *
+     * @param frameCls The class of the frame to be broadcasted.
+     * @param options Options to be passed to the frame's constructor.
+     */
+    async broadcastFrame(frameCls, options) {
+        await this._callEventHandler("on_broadcast_frame", frameCls, options);
+    }
+    /**
+     * Withdraw the speculation this strategy has in flight.
+     *
+     * Emitted rather than pushed so the host broadcasts it the same way it
+     * broadcasts the turn end. A withdrawal that took the queued path would
+     * reach a downstream gate *after* the turn end that follows it, and the
+     * gate would release the response the withdrawal was meant to discard.
+     */
+    async triggerUserTurnSpeculationCancelled() {
+        await this._callEventHandler("on_user_turn_speculation_cancelled");
+    }
+    /**
+     * Fire both `on_user_turn_inference_triggered` and `on_user_turn_stopped`.
+     *
+     * Most strategies call this when they decide a turn has ended. To
+     * defer finalization to another strategy (so this strategy fires
+     * only the inference-triggered event), wrap this strategy with
+     * `deferred()` instead of changing the trigger call.
+     */
+    async triggerUserTurnStopped(options = {}) {
+        await this.triggerUserTurnInferenceTriggered();
+        await this.triggerUserTurnFinalized({
+            enableUserSpeakingFrames: options.enableUserSpeakingFrames ?? null,
+        });
+    }
+    /** Trigger only the `on_user_turn_inference_triggered` event. */
+    async triggerUserTurnInferenceTriggered(options = {}) {
+        await this._callEventHandler("on_user_turn_inference_triggered", options.speculation ?? null);
+    }
+    /** Trigger only the `on_user_turn_stopped` event. */
+    async triggerUserTurnFinalized(options = {}) {
+        await this._callEventHandler("on_user_turn_stopped", new UserTurnStoppedParams({
+            enableUserSpeakingFrames: options.enableUserSpeakingFrames ?? this._enableUserSpeakingFrames,
+            confirmsSpeculation: options.confirmsSpeculation ?? false,
+        }));
+    }
+}
+//# sourceMappingURL=base_user_turn_stop_strategy.js.map

package/dist/turns/user_stop/deferred_user_turn_stop_strategy.d.ts

@@ -0,0 +1,81 @@
+/** Wrapper that defers a stop strategy's finalization to another strategy. */
+import type { Frame } from "../../frames/frames.ts";
+import type { FrameProcessorSetup } from "../../processors/frame_processor.ts";
+import type { EventHandlerFn } from "../../utils/base_object.ts";
+import type { ProcessFrameResult } from "../types.ts";
+import { BaseUserTurnStopStrategy, type BaseUserTurnStopStrategyOptions } from "./base_user_turn_stop_strategy.ts";
+/**
+ * Wraps a stop strategy and suppresses its `on_user_turn_stopped` event.
+ *
+ * Event subscriptions added to the wrapper are forwarded directly to
+ * the inner strategy, except for `on_user_turn_stopped`, which is
+ * dropped. The inner strategy's frame-side and inference-triggered
+ * events therefore reach external listeners (the controller, etc.)
+ * unchanged; finalization is left to another strategy in the chain
+ * such as `LLMTurnCompletionUserTurnStopStrategy`.
+ *
+ * Use the `deferred` helper for ergonomic construction:
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new LLMTurnCompletionUserTurnStopStrategy(),
+ * ]
+ */
+export declare class DeferredUserTurnStopStrategy extends BaseUserTurnStopStrategy {
+    protected _inner: BaseUserTurnStopStrategy;
+    /**
+     * @param inner The strategy whose finalization should be deferred.
+     * @param options Additional options forwarded to the base class.
+     */
+    constructor(inner: BaseUserTurnStopStrategy, options?: BaseUserTurnStopStrategyOptions);
+    /** Return the wrapped strategy. */
+    get inner(): BaseUserTurnStopStrategy;
+    /**
+     * Report what the inner strategy does with proposals.
+     *
+     * Frame processing is forwarded, so a proposal reaches the inner strategy
+     * and is resolved there. Deferring finalization changes when the turn ends,
+     * not who decides it.
+     */
+    get resolvesProposedTurnStopFrames(): boolean;
+    /**
+     * Forward event subscriptions to the inner strategy.
+     *
+     * `on_user_turn_stopped` is silently dropped — that's the whole point of
+     * the wrapper. Every other event handler is attached to the inner strategy
+     * directly, so the inner's events reach the listener without any per-event
+     * proxy method on the wrapper.
+     */
+    addEventHandler(eventName: string, handler: EventHandlerFn<this>): void;
+    /** Set up the inner strategy. */
+    setup(setup: FrameProcessorSetup): Promise<void>;
+    /** Clean up the inner strategy. */
+    cleanup(): Promise<void>;
+    /** Forward the turn-started callback to the inner strategy. */
+    handleUserTurnStarted(): Promise<void>;
+    /** Forward the turn-stopped callback to the inner strategy. */
+    handleUserTurnStopped(): Promise<void>;
+    /** Forward frame processing to the inner strategy. */
+    processFrame(frame: Frame): Promise<ProcessFrameResult | null>;
+}
+/**
+ * Defer this stop strategy's finalization to another strategy.
+ *
+ * Wraps `strategy` in a `DeferredUserTurnStopStrategy`: the inner strategy
+ * continues to drive inference-triggered events, but its
+ * `on_user_turn_stopped` event is suppressed. Use when another strategy in
+ * the chain (e.g. `LLMTurnCompletionUserTurnStopStrategy`) owns finalization.
+ *
+ * @example
+ * stop: [
+ *   deferred(new TurnAnalyzerUserTurnStopStrategy({ turnAnalyzer })),
+ *   new LLMTurnCompletionUserTurnStopStrategy(),
+ * ]
+ *
+ * @param strategy The stop strategy to defer.
+ * @returns A wrapper that exposes the inner strategy's behavior with
+ *   finalization suppressed.
+ */
+export declare function deferred(strategy: BaseUserTurnStopStrategy): DeferredUserTurnStopStrategy;
+//# sourceMappingURL=deferred_user_turn_stop_strategy.d.ts.map