@pipedog/core 0.0.0 → 0.1.0

package/dist/pipeline/worker.d.ts

@@ -0,0 +1,814 @@
+/**
+ * Pipeline worker implementation for managing frame processing pipelines.
+ *
+ * Provides the main PipelineWorker class that orchestrates pipeline
+ * execution, frame routing, lifecycle management, and monitoring capabilities
+ * including heartbeats, idle detection, and observer integration.
+ *
+ * Porting notes: the deprecated `PipelineTask` and `PipelineTaskParams`
+ * aliases, the `toolResources` option, the `ErrorFrame.fatal` branch, the
+ * deprecated `StartFrame` configuration fields and the legacy
+ * `setup_pipeline_task` setup hook name are not ported.
+ */
+import { Event, Queue, type Task } from "@pipedog/asyncio";
+import { BusCancelWorkerMessage, type BusEndWorkerMessage, BusFrameMessage, type BusMessage } from "../bus/index.ts";
+import { BusUIDataMessage } from "../bus/ui/messages.ts";
+import type { BaseClock } from "../clocks/base_clock.ts";
+import { type Frame, HeartbeatFrame, MetricsFrame, PipelineFlushFrame } from "../frames/frames.ts";
+import { BaseObserver, type FramePushed } from "../observers/base_observer.ts";
+import { TurnTrackingObserver } from "../observers/turn_tracking_observer.ts";
+import { UserBotLatencyObserver } from "../observers/user_bot_latency_observer.ts";
+import { FrameDirection, type FrameProcessor } from "../processors/frame_processor.ts";
+import { type RTVIObserverParams, RTVIProcessor } from "../processors/frameworks/rtvi/index.ts";
+import type { BaseTaskManager } from "../utils/asyncio/task_manager.ts";
+import type { FrameClass } from "../utils/frame_queue.ts";
+import { type OtelAttributeValue } from "../utils/tracing/setup.ts";
+import { TracingContext } from "../utils/tracing/tracing_context.ts";
+import { TurnTraceObserver } from "../utils/tracing/turn_trace_observer.ts";
+import { BaseWorker, type WorkerActivationArgs, type WorkerParams } from "../workers/base_worker.ts";
+import type { BasePipeline } from "./base_pipeline.ts";
+import { BotCapabilities } from "./capabilities.ts";
+import { Pipeline, PipelineSink, PipelineSource } from "./pipeline.ts";
+import { WorkerObserver } from "./worker_observer.ts";
+export declare const HEARTBEAT_SECS = 1;
+export declare const HEARTBEAT_MONITOR_SECS = 10;
+/** How often a pipeline answering someone else's flush says it is still working. */
+export declare const FLUSH_PROGRESS_PERIOD_SECS = 1;
+export declare const IDLE_TIMEOUT_SECS = 300;
+export declare const CANCEL_TIMEOUT_SECS = 20;
+export declare const SETUP_TIMEOUT_SECS = 20;
+export declare const START_TIMEOUT_SECS = 20;
+type AnyClass<T> = abstract new (...args: any[]) => T;
+export interface IdleFrameObserverOptions {
+    /** The event to set if the idle timeout frames are being pushed. */
+    idleEvent: Event;
+    /** The frames that should set the event when received. */
+    idleTimeoutFrames: readonly FrameClass[];
+}
+/**
+ * Idle timeout observer.
+ *
+ * Waits for specific frames being generated in the pipeline. If the frames
+ * are generated the given event is set. If the event is not set it means the
+ * pipeline is probably idle.
+ */
+export declare class IdleFrameObserver extends BaseObserver {
+    protected _idleEvent: Event;
+    protected _idleTimeoutFrames: readonly FrameClass[];
+    /**
+     * Initialize the observer.
+     *
+     * @param options.idleEvent The event to set if the idle timeout frames are being pushed.
+     * @param options.idleTimeoutFrames The frames that should set the event when received.
+     */
+    constructor(options: IdleFrameObserverOptions);
+    /**
+     * Callback executed when a frame is pushed in the pipeline.
+     *
+     * @param data The frame push event data.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+}
+/**
+ * What a pipeline worker does when a processor can no longer do its job.
+ *
+ * An unusable processor keeps failing for as long as the pipeline keeps using
+ * it, so the pipeline has to decide whether it is still worth running. A
+ * processor becomes unusable through a permanent error category or through
+ * `FrameProcessor.pushError` with `forceTreatAsPermanent: true`.
+ *
+ * - `CONTINUE`: report the error and keep running. The application can decide
+ *   what to do, for example by failing over to another provider.
+ * - `END`: end the pipeline gracefully, letting queued frames drain first.
+ * - `CANCEL`: cancel the pipeline immediately, abandoning queued frames.
+ */
+export declare const ProcessorUnusablePolicy: {
+    readonly CONTINUE: "continue";
+    readonly END: "end";
+    readonly CANCEL: "cancel";
+};
+export type ProcessorUnusablePolicy = (typeof ProcessorUnusablePolicy)[keyof typeof ProcessorUnusablePolicy];
+export interface PipelineParamsOptions {
+    audioInSampleRate?: number;
+    audioOutSampleRate?: number;
+    enableHeartbeats?: boolean;
+    enableMetrics?: boolean;
+    enableUsageMetrics?: boolean;
+    heartbeatsPeriodSecs?: number;
+    heartbeatsMonitorSecs?: number;
+    reportOnlyInitialTtfb?: boolean;
+    sendInitialEmptyMetrics?: boolean;
+    startMetadata?: Record<string, unknown>;
+}
+/**
+ * Configuration parameters for pipeline execution.
+ *
+ * These parameters are usually passed to all frame processors through
+ * FrameProcessorSetup. For other generic pipeline worker parameters use
+ * PipelineWorker constructor options instead.
+ *
+ * - `audioInSampleRate`: input audio sample rate in Hz.
+ * - `audioOutSampleRate`: output audio sample rate in Hz.
+ * - `enableHeartbeats`: whether to enable heartbeat monitoring.
+ * - `enableMetrics`: whether to enable metrics collection.
+ * - `enableUsageMetrics`: whether to enable usage metrics.
+ * - `heartbeatsPeriodSecs`: period between heartbeats in seconds.
+ * - `heartbeatsMonitorSecs`: timeout (in seconds) before warning about missed
+ *   heartbeats. Defaults to 10 seconds.
+ * - `reportOnlyInitialTtfb`: whether to report only initial time to first byte.
+ * - `sendInitialEmptyMetrics`: whether to send initial empty metrics.
+ * - `startMetadata`: additional metadata for pipeline start.
+ */
+export declare class PipelineParams {
+    audioInSampleRate: number;
+    audioOutSampleRate: number;
+    enableHeartbeats: boolean;
+    enableMetrics: boolean;
+    enableUsageMetrics: boolean;
+    heartbeatsPeriodSecs: number;
+    heartbeatsMonitorSecs: number;
+    reportOnlyInitialTtfb: boolean;
+    sendInitialEmptyMetrics: boolean;
+    startMetadata: Record<string, unknown>;
+    constructor(options?: PipelineParamsOptions);
+}
+export interface PipelineWorkerOptions {
+    /** Whether the worker starts active. Forwarded to `BaseWorker`. */
+    active?: boolean;
+    /**
+     * Optional attributes to propagate as OpenTelemetry conversation span
+     * attributes.
+     */
+    additionalSpanAttributes?: Record<string, OtelAttributeValue> | null;
+    /**
+     * Optional application-defined bag of anything your application code may
+     * want to share across this session (DB handles, HTTP clients, etc.),
+     * passed by reference. Pipecat passes it through untouched and exposes it
+     * on the worker itself as `worker.appResources` and passes it to tool
+     * handlers as `FunctionCallParams.appResources`. The framework never copies
+     * or clears this object; the caller retains their handle and can read any
+     * mutations after the worker finishes.
+     */
+    appResources?: unknown;
+    /**
+     * Bridge configuration. `null` means the pipeline is not bridged. An empty
+     * array `[]` wraps the pipeline with bus edge processors that accept frames
+     * from all bridges. An array of names like `["voice"]` accepts only frames
+     * from those bridges. The bus comes from `attach()` (called by the runner).
+     */
+    bridged?: readonly string[] | null;
+    /**
+     * Whether reaching the idle timeout should cancel the pipeline worker. When
+     * false, the idle event still fires `on_idle_timeout` but the worker is
+     * left alone (and `cancelRunnerOnIdleTimeout` is ignored too: opting out of
+     * local cancellation also opts out of the runner-wide cancel).
+     */
+    cancelOnIdleTimeout?: boolean;
+    /**
+     * When `cancelOnIdleTimeout` is also true, whether reaching the idle
+     * timeout should also cancel the entire `WorkerRunner`. The worker is
+     * always cancelled first; when this is true the worker also emits a
+     * `BusCancelMessage` so the runner broadcasts cancellation to every other
+     * root worker. Defaults to true so a multi-worker bot's helpers shut down
+     * with the main pipeline; set to false for a sidecar `PipelineWorker` that
+     * should self-cancel on idle without bringing down its peers.
+     */
+    cancelRunnerOnIdleTimeout?: boolean;
+    /** Timeout (in seconds) to wait for cancellation to happen cleanly. */
+    cancelTimeoutSecs?: number;
+    /**
+     * What the bot does, for fields the pipeline can't show. Its known fields
+     * replace the ones derived from the pipeline's transports and parameters.
+     * See `capabilities`.
+     */
+    capabilities?: BotCapabilities | null;
+    /**
+     * Whether to warn about tasks left running when the worker finishes. Only
+     * applies when the worker owns its task manager; otherwise the runner
+     * reports dangling tasks.
+     */
+    checkDanglingTasks?: boolean;
+    /** Clock implementation for timing operations. */
+    clock?: BaseClock | null;
+    /** Optional custom ID for the conversation. */
+    conversationId?: string | null;
+    /** Whether to enable tracing. */
+    enableTracing?: boolean;
+    /** Whether to enable turn tracking. */
+    enableTurnTracking?: boolean;
+    /**
+     * Whether this worker answers a flush probe, bouncing it at the sink and
+     * completing it at the source. Defaults to whether the pipeline is
+     * unbridged, so a worker wired into someone else's topology leaves the
+     * probe to travel on and be completed by the pipeline that owns the
+     * transport. A bridged worker with no such peer never completes a flush and
+     * every `flushPipeline` call waits out its timeout.
+     */
+    handleFlushFrame?: boolean | null;
+    /**
+     * Whether to automatically add RTVI support to the pipeline. `null`, the
+     * default, adds it unless the pipeline is bridged: a bridged worker has no
+     * client of its own, and its RTVI would report every frame a second time as
+     * it crosses the bridge.
+     */
+    enableRtvi?: boolean | null;
+    /**
+     * When `bridged` is set, extra frame types that should not cross the bus
+     * (lifecycle frames are always excluded).
+     */
+    excludeFrames?: readonly FrameClass[] | null;
+    /**
+     * The frames that should trigger an idle timeout if not received within
+     * `idleTimeoutSecs`. The default pairs the VAD-only `UserSpeakingFrame` with
+     * the turn and transcription frames a provider-driven pipeline reports
+     * instead.
+     */
+    idleTimeoutFrames?: readonly FrameClass[];
+    /**
+     * Timeout (in seconds) to consider pipeline idle, or null. If a pipeline is
+     * idle the pipeline worker will be cancelled automatically.
+     */
+    idleTimeoutSecs?: number | null;
+    /** Optional worker name (used for worker-style addressing on the bus). */
+    name?: string | null;
+    /** Observers for monitoring pipeline execution. */
+    observers?: BaseObserver[] | null;
+    /**
+     * What to do when a processor reports an error that leaves it unable to do
+     * its job, such as a service whose API key was rejected. Defaults to
+     * `ProcessorUnusablePolicy.CONTINUE`, leaving the decision to
+     * `on_pipeline_error` handlers.
+     */
+    processorUnusablePolicy?: ProcessorUnusablePolicy;
+    /** Configuration parameters for the pipeline. */
+    params?: PipelineParams | null;
+    /** The RTVI processor to add if RTVI is enabled. */
+    rtviProcessor?: RTVIProcessor | null;
+    /** The RTVI observer parameters to use if RTVI is enabled. */
+    rtviObserverParams?: RTVIObserverParams | null;
+    /**
+     * Timeout (in seconds) to wait for every processor to be set up. Processors
+     * connect while they are set up, so one that blocks connecting never lets
+     * the pipeline start, and the worker is torn down instead of waiting
+     * forever. The `StartFrame` is pushed while processors are still being set
+     * up, and each processor holds it only until its own setup is done, so
+     * processors ahead of a slow one start without it.
+     */
+    setupTimeoutSecs?: number;
+    /**
+     * Timeout (in seconds) to wait for the `StartFrame` to reach the end of the
+     * pipeline, counted from when every processor is set up. A processor that
+     * blocks while handling it never lets the pipeline start, so the worker is
+     * torn down instead of waiting forever.
+     */
+    startTimeoutSecs?: number;
+    /** Optional task manager for handling tasks. */
+    taskManager?: BaseTaskManager | null;
+}
+/**
+ * Manages the execution of a pipeline, handling frame processing and worker
+ * lifecycle.
+ *
+ * Orchestrates pipeline execution with comprehensive monitoring, event
+ * handling, and lifecycle management. Provides event handlers for various
+ * pipeline states and frame types, idle detection, heartbeat monitoring, and
+ * observer integration.
+ *
+ * Event handlers available:
+ *
+ * - on_frame_reached_upstream: called when upstream frames reach the source
+ * - on_frame_reached_downstream: called when downstream frames reach the sink
+ * - on_heartbeat_timeout: called when a heartbeat frame is not received within
+ *   the monitor timeout. Fires repeatedly every `heartbeatsMonitorSecs` for as
+ *   long as the stall persists.
+ * - on_idle_timeout: called when pipeline is idle beyond timeout threshold
+ * - on_pipeline_started: called when pipeline starts with StartFrame
+ * - on_pipeline_finished: called after the pipeline has reached any terminal
+ *   state. This includes:
+ *     - StopFrame: pipeline was stopped (processors keep connections open)
+ *     - EndFrame: pipeline ended normally
+ *     - CancelFrame: pipeline was cancelled
+ *
+ *   Use this event for cleanup, logging, or post-processing tasks. Users can
+ *   inspect the frame if they need to handle specific cases.
+ * - on_pipeline_timeout: called when a frame the worker was waiting on never
+ *   reached the end of the pipeline, meaning a processor is blocked. Inspect
+ *   the frame to tell the cases apart:
+ *     - StartFrame: the pipeline never started and is being torn down
+ *     - CancelFrame: the pipeline was cancelled but did not drain
+ *
+ *   There is no EndFrame case: ending flushes whatever is queued, so the
+ *   worker waits for it however long that takes.
+ * - on_pipeline_error: called when an error occurs with ErrorFrame. Handler
+ *   can read `frame.processor.isUsable` to distinguish between errors that
+ *   end a processor's usability from those that don't.
+ * - on_setup_timeout: called when setting the pipeline up times out.
+ *
+ * @example
+ * worker.eventHandler("on_frame_reached_upstream", async (worker, frame) => { ... });
+ * worker.eventHandler("on_heartbeat_timeout", async (worker) => { ... });
+ * worker.eventHandler("on_idle_timeout", async (worker) => { ... });
+ * worker.eventHandler("on_pipeline_started", async (worker, frame) => { ... });
+ * worker.eventHandler("on_pipeline_finished", async (worker, frame) => { ... });
+ * worker.eventHandler("on_pipeline_timeout", async (worker, frame) => { ... });
+ * worker.eventHandler("on_pipeline_error", async (worker, frame) => { ... });
+ * worker.eventHandler("on_setup_timeout", async (worker) => { ... });
+ */
+export declare class PipelineWorker extends BaseWorker {
+    protected _bridged: readonly string[] | null;
+    protected _handleFlushFrame: boolean;
+    protected _params: PipelineParams;
+    protected _capabilitiesOverride: BotCapabilities;
+    protected _additionalSpanAttributes: Record<string, OtelAttributeValue>;
+    protected _cancelOnIdleTimeout: boolean;
+    protected _cancelRunnerOnIdleTimeout: boolean;
+    protected _cancelTimeoutSecs: number;
+    protected _framesReachingSink: number;
+    protected _foreignProbes: Map<number, string>;
+    protected _flushProgress: Map<number, number>;
+    protected _flushProgressSent: number;
+    protected _setupTimeoutSecs: number;
+    protected _startTimeoutSecs: number;
+    protected _clock: BaseClock;
+    protected _conversationId: string | null;
+    protected _enableTracing: boolean;
+    protected _enableTurnTracking: boolean;
+    protected _idleTimeoutSecs: number | null;
+    protected _appResources: unknown;
+    protected _processorUnusablePolicy: ProcessorUnusablePolicy;
+    protected _unusableProcessors: Set<FrameProcessor>;
+    protected _turnTrackingObserver: TurnTrackingObserver | null;
+    protected _userBotLatencyObserver: UserBotLatencyObserver | null;
+    protected _turnTraceObserver: TurnTraceObserver | null;
+    protected _tracingContext: TracingContext | null;
+    protected _finished: boolean;
+    protected _cancelled: boolean;
+    protected _pushQueue: Queue<Frame>;
+    protected _processPushTask: Task<unknown> | null;
+    protected _pipelineSetupTask: Task<unknown> | null;
+    protected _pipelineStartTask: Task<boolean | undefined> | null;
+    protected _setupWatchTask: Task<unknown> | null;
+    protected _heartbeatQueue: Queue<HeartbeatFrame>;
+    protected _heartbeatPushTask: Task<unknown> | null;
+    protected _heartbeatMonitorTask: Task<unknown> | null;
+    protected _rtvi: RTVIProcessor | null;
+    protected _idleEvent: Event;
+    protected _idleMonitorTask: Task<unknown> | null;
+    protected _pipelineStartEvent: Event;
+    protected _pipelineEndEvent: Event;
+    protected _source: PipelineSource;
+    protected _sink: PipelineSink;
+    protected _pipeline: Pipeline;
+    protected _observer: WorkerObserver;
+    protected _reachedUpstreamTypes: Set<FrameClass>;
+    protected _reachedDownstreamTypes: Set<FrameClass>;
+    /**
+     * Initialize the PipelineWorker.
+     *
+     * @param pipeline The pipeline to execute.
+     * @param options See `PipelineWorkerOptions`.
+     */
+    constructor(pipeline: BasePipeline, options?: PipelineWorkerOptions);
+    /** The pipeline parameters for this worker. */
+    get params(): PipelineParams;
+    /**
+     * What the bot does in this session.
+     *
+     * Derived from the media the pipeline's transports send and receive and
+     * from `PipelineParams.enableMetrics`, with the `capabilities` passed to the
+     * constructor applied on top. A field no transport reports is `null`
+     * (unknown). RTVI sends this to the client in `bot-ready`.
+     */
+    get capabilities(): BotCapabilities;
+    /** Whether this pipeline is bridged onto the bus. */
+    get bridged(): boolean;
+    /**
+     * The application-defined resources passed to this worker.
+     *
+     * This is the same object passed to the constructor as `appResources`. Tool
+     * handlers can also access it via `FunctionCallParams.appResources`. The
+     * framework returns the original reference; mutations are visible to all
+     * callers. `null` if none were passed.
+     */
+    get appResources(): unknown;
+    /**
+     * The full pipeline managed by this pipeline worker. This also includes any
+     * internal processors added by the pipeline worker.
+     */
+    get pipeline(): BasePipeline;
+    /** The turn tracking observer if enabled, or null. */
+    get turnTrackingObserver(): TurnTrackingObserver | null;
+    /** The turn trace observer if enabled, or null. */
+    get turnTraceObserver(): TurnTraceObserver | null;
+    /** The RTVI processor added to the pipeline when RTVI is enabled. */
+    get rtvi(): RTVIProcessor;
+    /** Frame types that trigger the on_frame_reached_upstream event. */
+    get reachedUpstreamTypes(): FrameClass[];
+    /** Frame types that trigger the on_frame_reached_downstream event. */
+    get reachedDownstreamTypes(): FrameClass[];
+    /**
+     * Add an observer to monitor pipeline execution.
+     *
+     * @param observer The observer to add to the pipeline monitoring.
+     */
+    addObserver(observer: BaseObserver): void;
+    /**
+     * Remove an observer from pipeline monitoring.
+     *
+     * @param observer The observer to remove from pipeline monitoring.
+     */
+    removeObserver(observer: BaseObserver): Promise<void>;
+    /**
+     * Set which frame types trigger the on_frame_reached_upstream event.
+     *
+     * @param types Frame types to monitor for upstream events.
+     */
+    setReachedUpstreamFilter(types: readonly FrameClass[]): void;
+    /**
+     * Set which frame types trigger the on_frame_reached_downstream event.
+     *
+     * @param types Frame types to monitor for downstream events.
+     */
+    setReachedDownstreamFilter(types: readonly FrameClass[]): void;
+    /**
+     * Add frame types to trigger the on_frame_reached_upstream event.
+     *
+     * @param types Frame types to add to upstream monitoring.
+     */
+    addReachedUpstreamFilter(types: readonly FrameClass[]): void;
+    /**
+     * Add frame types to trigger the on_frame_reached_downstream event.
+     *
+     * @param types Frame types to add to downstream monitoring.
+     */
+    addReachedDownstreamFilter(types: readonly FrameClass[]): void;
+    /**
+     * Check if the pipeline worker has finished execution.
+     *
+     * This indicates whether the worker has finished, meaning all processors
+     * have stopped.
+     *
+     * @returns True if all processors have stopped and the worker is complete.
+     */
+    hasFinished(): boolean;
+    /**
+     * Schedule the pipeline to stop after processing all queued frames.
+     *
+     * Sends an EndFrame to gracefully terminate the pipeline once all current
+     * processing is complete.
+     */
+    stopWhenDone(): Promise<void>;
+    /**
+     * Request a graceful end of the session, draining the pipeline first.
+     *
+     * Whatever this worker has already pushed reaches the end of the pipeline
+     * before the session goes away, rather than being cut off wherever it
+     * happened to be.
+     *
+     * @param options.reason Optional human-readable reason for ending.
+     */
+    end(options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /**
+     * Activate a worker by name, draining this pipeline when handing over.
+     *
+     * Deactivating this worker before its pipeline drains would let the target
+     * start producing while this worker's output is still in flight, and both
+     * would arrive interleaved. A worker that stays active is handing nothing
+     * over, so it doesn't wait: the first activation of a session would
+     * otherwise wait on the very worker it is about to wake.
+     *
+     * @param workerName The name of the worker to activate.
+     * @param options.args Optional `WorkerActivationArgs` forwarded to the
+     *   target worker's `onActivated`.
+     * @param options.deactivateSelf Whether to deactivate this worker before
+     *   activating the target. Deactivating this worker drains its pipeline
+     *   first; staying active does not. A worker that stays active and wants to
+     *   drain anyway can call `flushPipeline` before this.
+     */
+    activateWorker(workerName: string, options?: {
+        args?: WorkerActivationArgs | null;
+        deactivateSelf?: boolean;
+    }): Promise<void>;
+    /**
+     * Wait for in-flight frames to be processed, if any can be.
+     *
+     * A pipeline that is not running has no one left to bounce the flush probe
+     * back, so waiting on it would only spend the flush timeout.
+     * `_processPushTask` is created with the worker's tasks and cleared once
+     * they are torn down, so it stands for whether there is a pipeline to
+     * drain.
+     */
+    protected _drainPipeline(): Promise<void>;
+    /**
+     * Request the running pipeline to cancel.
+     *
+     * @param options.reason Optional reason to indicate why the pipeline is being cancelled.
+     */
+    cancel(options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /**
+     * Start and manage the pipeline execution until completion or cancellation.
+     *
+     * @param params Configuration parameters for pipeline execution.
+     */
+    run(params: WorkerParams): Promise<void>;
+    /**
+     * Queue a single frame to be pushed through the pipeline.
+     *
+     * Downstream frames are pushed from the beginning of the pipeline. Upstream
+     * frames are pushed from the end of the pipeline.
+     *
+     * @param frame The frame to be processed.
+     * @param direction The direction to push the frame. Defaults to downstream.
+     */
+    queueFrame(frame: Frame, direction?: FrameDirection): Promise<void>;
+    /**
+     * Queue multiple frames to be pushed through the pipeline.
+     *
+     * Downstream frames are pushed from the beginning of the pipeline. Upstream
+     * frames are pushed from the end of the pipeline.
+     *
+     * @param frames An iterable or async iterable of frames to be processed.
+     * @param direction The direction to push the frames. Defaults to downstream.
+     */
+    queueFrames(frames: Iterable<Frame> | AsyncIterable<Frame>, direction?: FrameDirection): Promise<void>;
+    /**
+     * Flush all in-flight frames from the pipeline and wait for it to drain.
+     *
+     * Pushes a `PipelineFlushFrame` downstream; the sink bounces it back
+     * upstream, the source turns it around, and its event is set when it
+     * reaches the sink a second time. By then every frame queued ahead of it
+     * has been processed, along with anything a processor started by pushing
+     * upstream. The probe goes on the worker's push queue, behind whatever is
+     * already waiting there, and bypasses any `queueFrame` override (e.g.
+     * tool-call deferral).
+     *
+     * @param timeout Seconds of no progress before giving up. Progress is a
+     *   frame reaching this worker's sink, or a report from the pipeline
+     *   answering the probe when it crossed into another worker. A pipeline
+     *   still working keeps the wait alive, however long it takes; one that is
+     *   stuck, or that nobody will answer, gives up after this much quiet. On
+     *   giving up a warning is logged and `false` is returned rather than
+     *   blocking forever.
+     * @returns True if the pipeline drained, false if it went quiet first.
+     */
+    flushPipeline(timeout?: number): Promise<boolean>;
+    /**
+     * Report progress on a probe from another worker while we hold it.
+     *
+     * Called by whoever brings the probe into this pipeline, since only they
+     * know it is really coming in: every worker on the bus sees it, but most of
+     * them have nowhere to put it.
+     *
+     * @param frame The flush probe entering this pipeline.
+     */
+    trackFlushProbe(frame: PipelineFlushFrame): void;
+    /**
+     * Handle outbound bus messages: TTS playback and RTVI UI translation.
+     *
+     * Runs the base lifecycle/job dispatch first. A `BusTTSSpeakMessage`
+     * targeted at this worker is queued as a `TTSSpeakFrame` (pipelines without
+     * a TTS service let it flow through). When this worker owns the RTVI
+     * processor, UI carriers produced by a `UIWorker` (`BusUIDataMessage`
+     * subclasses) are translated into RTVI frames by `_handleUiBusMessage`;
+     * other workers skip the translation.
+     */
+    onBusMessage(message: BusMessage): Promise<void>;
+    /**
+     * Queue a frame that reached this worker over the bus.
+     *
+     * Queued rather than pushed from the edge that captured the outbound
+     * direction, so bus inbound serialises with the frames this worker queues
+     * itself (e.g. those a flow framework enqueues from `setNode`).
+     *
+     * @param message The frame carrier to inject.
+     */
+    protected _queueBridgedFrame(message: BusFrameMessage): Promise<void>;
+    /**
+     * Translate a UI carrier into the matching RTVI frame and queue it.
+     *
+     * Called only when this worker owns the RTVI processor. The `RTVIObserver`
+     * later wraps the queued frame into a typed `ui-command` / `ui-job-group`
+     * envelope for the client. Inbound carriers (e.g. `BusUIEventMessage`)
+     * match no branch and are ignored.
+     */
+    protected _handleUiBusMessage(message: BusUIDataMessage): Promise<void>;
+    /**
+     * Republish an inbound client UI message onto the bus.
+     *
+     * Translates a typed RTVI UI message from the client (`UIEventMessage`,
+     * `UISnapshotMessage`, or `UICancelJobGroupMessage`) into a single
+     * `BusUIEventMessage` carrier so `UIWorker` subscribers can dispatch it.
+     * This is the inbound counterpart of `onBusMessage`. Unrecognized message
+     * types are ignored.
+     */
+    protected _republishUiMessageOnBus(message: unknown): Promise<void>;
+    /** Stop processors still setting up; they keep holding the StartFrame. */
+    protected _cancelPipelineSetup(): Promise<void>;
+    /** Stop waiting for the pipeline to start, so it is only cleaned up. */
+    protected _cancelPipelineStart(): Promise<void>;
+    /**
+     * Internal cancellation logic for the pipeline worker.
+     *
+     * @param options.reason Optional reason to indicate why the pipeline is being cancelled.
+     */
+    protected _cancel(options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /** Create and start all pipeline processing tasks. */
+    protected _createTasks(): Promise<void>;
+    /**
+     * Give up on a pipeline whose processors don't finish setting up.
+     *
+     * Setting up is cancelled, so the processors still being set up keep
+     * holding the StartFrame: the pipeline never starts and is only cleaned up,
+     * as when setting the worker up times out.
+     */
+    protected _watchPipelineSetup(): Promise<void>;
+    /** Start heartbeat tasks if heartbeats are enabled and not already running. */
+    protected _maybeStartHeartbeatTasks(): void;
+    /** Start the idle monitoring task if an idle timeout is configured. */
+    protected _maybeStartIdleTask(): void;
+    /** Cancel all running pipeline tasks. */
+    protected _cancelTasks(): Promise<void>;
+    /** Cancel heartbeat tasks if they are running. */
+    protected _maybeCancelHeartbeatTasks(): Promise<void>;
+    /** Cancel the idle monitoring task if it is running. */
+    protected _maybeCancelIdleTask(): Promise<void>;
+    /** Create an initial metrics frame with zero values for all processors. */
+    protected _initialMetricsFrame(): MetricsFrame;
+    /**
+     * Push the StartFrame and wait for the pipeline to start.
+     *
+     * Pushing it waits too, while the pipeline is still held, so cancelling
+     * this task gives up on both.
+     *
+     * @returns Whether the pipeline started; see `_waitForPipelineStart`.
+     */
+    protected _startPipeline(): Promise<boolean>;
+    /**
+     * Wait for the start task, and return whether it started the pipeline (a
+     * cancelled one didn't).
+     */
+    protected _waitForStartTask(): Promise<boolean>;
+    /**
+     * Wait for the specified start frame to reach the end of the pipeline.
+     *
+     * @returns Whether the pipeline started. A pipeline that doesn't start
+     *   within `startTimeoutSecs` is torn down, since nothing pushed into it
+     *   afterwards would be processed.
+     */
+    protected _waitForPipelineStart(frame: Frame): Promise<boolean>;
+    /** Wait for the specified frame to reach the end of the pipeline. */
+    protected _waitForPipelineEnd(frame: Frame): Promise<void>;
+    protected _waitForPipelineFinished(): Promise<void>;
+    /**
+     * Set up the pipeline worker, bounded by a timeout.
+     *
+     * Processors are only started being set up here; their setup is bounded
+     * separately by `_watchPipelineSetup`.
+     *
+     * @returns Whether the worker was set up. Setup files and observers that
+     *   block never let the pipeline start, so setting up is abandoned once
+     *   `setupTimeoutSecs` elapses.
+     */
+    protected _setupWithinTimeout(params: WorkerParams): Promise<boolean>;
+    /** Set up the pipeline worker and all processors. */
+    protected _setup(params: WorkerParams): Promise<void>;
+    /**
+     * Release the pipeline once it is set up, unless setting up was abandoned.
+     *
+     * A cancelled setup (timed out, or the worker was cancelled) keeps the
+     * StartFrame held, so the pipeline never starts and is only cleaned up.
+     */
+    protected _pipelineSetupDone(task: Task<unknown>): void;
+    /** Clean up the pipeline worker and processors. */
+    protected _cleanup(cleanupPipeline: boolean): Promise<void>;
+    /**
+     * Cancel the children once this worker's pipeline is over.
+     *
+     * A pipeline that ends on its own (an `EndFrame` it queued itself, an idle
+     * timeout, a permanent error) is never told to end over the bus, so nothing
+     * has passed the end on to its children. A child that has already finished
+     * takes no notice.
+     */
+    protected _cancelChildren(): Promise<void>;
+    /**
+     * End the pipeline after propagating end to children.
+     *
+     * Drives shutdown through the pipeline (`EndFrame`) so `_finishedEvent`
+     * fires once the frame drains through the sink, rather than calling
+     * `stop()` directly.
+     */
+    protected _handleWorkerEnd(message: BusEndWorkerMessage): Promise<void>;
+    /**
+     * Cancel the pipeline after propagating cancel to children.
+     *
+     * Drives shutdown through the pipeline (`CancelFrame`) so `_finishedEvent`
+     * fires once the frame drains, rather than calling `stop()` directly.
+     *
+     * Children are told whatever state this worker is in: one that cancelled
+     * itself earlier, on an idle timeout or a permanent error, still has to
+     * pass the runner's cancel on.
+     */
+    protected _handleWorkerCancel(message: BusCancelWorkerMessage): Promise<void>;
+    /**
+     * Process frames from the push queue and send them through the pipeline.
+     *
+     * Once the start task has started the pipeline, it pushes the frames queued
+     * by the user. It runs until the worker is cancelled or stopped (e.g. with
+     * an EndFrame).
+     */
+    protected _processPushQueue(): Promise<void>;
+    /**
+     * Move a flush probe along its trip, settling it once it is done.
+     *
+     * The probe travels down to the sink, back up to the source, then down
+     * again, and only the second arrival at the sink settles it. The extra leg
+     * is what makes the probe wait for work a processor starts by pushing
+     * upstream: an `LLMContextFrame` pushed up after a function call result,
+     * say, whose response only comes back down afterwards. A probe that stopped
+     * at the source would return while that response was still being
+     * generated, or still being synthesized.
+     *
+     * @param frame The probe, carrying the event its initiator awaits.
+     * @param atSink Whether the probe has arrived at the sink or the source.
+     */
+    protected _advanceFlushProbe(frame: PipelineFlushFrame, atSink: boolean): Promise<void>;
+    /**
+     * Tell whoever is waiting on a probe we hold that we are still working.
+     *
+     * Their own sink sees nothing while we drain, so without this they can only
+     * conclude the pipeline has gone quiet. Sent no more than once a second: it
+     * says the flush is alive, not how much is left.
+     */
+    protected _reportFlushProgress(): Promise<void>;
+    /**
+     * Process frames coming upstream from the pipeline.
+     *
+     * These frames might indicate, for example, that we want the pipeline to be
+     * stopped (e.g. EndWorkerFrame) in which case we would send an EndFrame
+     * down the pipeline.
+     */
+    protected _sourcePushFrame(frame: Frame, _direction: FrameDirection): Promise<void>;
+    /**
+     * Apply the unusable-processor policy, once per processor.
+     *
+     * A processor that can no longer do its job keeps failing for as long as
+     * the pipeline keeps using it, so the policy is applied to the first error
+     * that says so and not to the ones that follow.
+     *
+     * @param processor The processor that can no longer do its job.
+     */
+    protected _handleUnusableProcessor(processor: FrameProcessor): Promise<void>;
+    /**
+     * Process frames coming downstream from the pipeline.
+     *
+     * Processes frames coming downstream from the pipeline. For example,
+     * heartbeat frames or an EndFrame which would indicate all processors have
+     * handled the EndFrame and therefore we can exit the worker cleanly.
+     */
+    protected _sinkPushFrame(frame: Frame, _direction: FrameDirection): Promise<void>;
+    /** Push heartbeat frames at regular intervals. */
+    protected _heartbeatPushHandler(): Promise<void>;
+    /**
+     * Monitor heartbeat frames for processing time and timeout detection.
+     *
+     * Logs the time each heartbeat takes to traverse the pipeline. If no
+     * heartbeat arrives within `heartbeatsMonitorSecs`, logs a warning and
+     * fires `on_heartbeat_timeout`. The event fires repeatedly every
+     * `heartbeatsMonitorSecs` for as long as the stall persists.
+     */
+    protected _heartbeatMonitorHandler(): Promise<void>;
+    /**
+     * Monitor pipeline activity and detect idle conditions.
+     *
+     * Tracks frame activity and triggers idle timeout events when the pipeline
+     * hasn't received relevant frames within the timeout period.
+     *
+     * Note: Heartbeats are excluded from idle detection.
+     */
+    protected _idleMonitorHandler(): Promise<void>;
+    /**
+     * Handle idle timeout detection and optional cancellation.
+     *
+     * @returns Whether the pipeline worker should continue running.
+     */
+    protected _idleTimeoutDetected(): Promise<boolean>;
+    /**
+     * Run `setupPipelineWorker` from each file in `PIPECAT_SETUP_FILES`.
+     *
+     * A setup file may define `setupPipelineWorker(worker)` to attach event
+     * handlers, observers, or other per-worker wiring.
+     */
+    protected _loadSetupFiles(): Promise<void>;
+    /** Build and return start metadata including user-provided values. */
+    protected _createStartMetadata(): Record<string, unknown>;
+    /** Recursively yield the processors of the given type(s) in the pipeline. */
+    protected _iterProcessors<T>(processor: FrameProcessor, processorTypes: readonly AnyClass<T>[]): Generator<T>;
+}
+export {};
+//# sourceMappingURL=worker.d.ts.map