@pipedog/core 0.0.0 → 0.2.0

package/dist/bus/messages.js

@@ -0,0 +1,357 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/bus/messages.py
+import { defineMixin } from "../utils/mixin.js";
+import { objCount, objId } from "../utils/utils.js";
+/**
+ * Base class for messages carried by the `WorkerBus`.
+ *
+ * Bus messages are independent of pipeline `Frame`s — if a worker needs to
+ * ship a frame between pipelines it wraps it in a `BusFrameMessage`.
+ * Subclasses choose delivery priority by extending `BusDataMessage` (normal
+ * priority, FIFO) or `BusSystemMessage` (high priority, delivered ahead of
+ * queued data messages).
+ *
+ * - `id`: unique identifier for the message instance.
+ * - `name`: human-readable name combining class name and instance count.
+ * - `source`: name of the worker or component that sent this message.
+ * - `target`: name of the intended recipient worker, or null for broadcast.
+ */
+export class BusMessage {
+    id = objId();
+    name = `${this.constructor.name}#${objCount(this)}`;
+    source;
+    target;
+    constructor(options) {
+        this.source = options.source;
+        this.target = options.target ?? null;
+    }
+    toString() {
+        return `${this.name} (source=${this.source}, target=${this.target})`;
+    }
+}
+export const BusLocalMessage = defineMixin("BusLocalMessage", (Base) => {
+    class BusLocalMessageMixin extends Base {
+    }
+    return BusLocalMessageMixin;
+});
+/**
+ * Normal-priority bus message.
+ *
+ * Delivered in FIFO order on the subscriber's data queue.
+ */
+export class BusDataMessage extends BusMessage {
+}
+/**
+ * High-priority bus message.
+ *
+ * Delivered ahead of any queued `BusDataMessage` on the subscriber's priority
+ * queue.
+ */
+export class BusSystemMessage extends BusMessage {
+}
+/** Wraps a Pipecat `Frame` for transport over the bus. */
+export class BusFrameMessage extends BusDataMessage {
+    frame;
+    direction;
+    bridge;
+    constructor(options) {
+        super(options);
+        this.frame = options.frame;
+        this.direction = options.direction;
+        this.bridge = options.bridge ?? null;
+    }
+    toString() {
+        return `${this.name}(frame: ${this.frame}, direction: ${this.direction}, bridge: ${this.bridge})`;
+    }
+}
+/**
+ * Asks a `PipelineWorker` to speak the given text via its TTS service.
+ *
+ * On receipt, the worker queues a `TTSSpeakFrame` into its pipeline.
+ * Pipelines without a TTS service let the frame flow through harmlessly.
+ */
+export class BusTTSSpeakMessage extends BusDataMessage {
+    text;
+    appendToContext;
+    constructor(options) {
+        super(options);
+        this.text = options.text;
+        this.appendToContext = options.appendToContext ?? true;
+    }
+}
+/**
+ * Reports that a flush probe from another worker is still making progress.
+ *
+ * A probe that crosses into another pipeline is answered there, so the worker
+ * waiting on it cannot see whether anything is happening. The pipeline
+ * holding the probe says so, and the wait stays alive for as long as it keeps
+ * saying it.
+ */
+export class BusFlushProgressMessage extends BusDataMessage {
+    flushId;
+    constructor(options) {
+        super(options);
+        this.flushId = options.flushId;
+    }
+}
+/** Tells a targeted worker to become active and start processing. */
+export class BusActivateWorkerMessage extends BusDataMessage {
+    args;
+    constructor(options) {
+        super(options);
+        this.args = options.args ?? null;
+    }
+}
+/** Tells a targeted worker to become inactive and stop processing. */
+export class BusDeactivateWorkerMessage extends BusDataMessage {
+}
+/**
+ * Request a graceful end of the session.
+ *
+ * Sent by a worker to the runner, which responds by sending
+ * `BusEndWorkerMessage` to each worker.
+ */
+export class BusEndMessage extends BusDataMessage {
+    /** Optional human-readable reason for ending. */
+    reason;
+    constructor(options) {
+        super(options);
+        this.reason = options.reason ?? null;
+    }
+}
+/**
+ * Tells a targeted worker to end its pipeline gracefully.
+ *
+ * Sent by the runner to individual workers during shutdown.
+ */
+export class BusEndWorkerMessage extends BusDataMessage {
+    /** Optional human-readable reason for ending. */
+    reason;
+    constructor(options) {
+        super(options);
+        this.reason = options.reason ?? null;
+    }
+}
+/**
+ * Request a hard cancel of the session.
+ *
+ * Sent by a worker to the runner, which responds by sending
+ * `BusCancelWorkerMessage` to each worker.
+ */
+export class BusCancelMessage extends BusSystemMessage {
+    /** Optional human-readable reason for the cancellation. */
+    reason;
+    constructor(options) {
+        super(options);
+        this.reason = options.reason ?? null;
+    }
+}
+/**
+ * Tells a targeted worker to cancel its pipeline.
+ *
+ * Sent by the runner to individual workers during cancellation.
+ */
+export class BusCancelWorkerMessage extends BusSystemMessage {
+    /** Optional human-readable reason for the cancellation. */
+    reason;
+    constructor(options) {
+        super(options);
+        this.reason = options.reason ?? null;
+    }
+}
+/**
+ * Request to add a worker to the local runner.
+ *
+ * Local-only: carries an in-memory worker reference that cannot be
+ * serialized over the network.
+ */
+export class BusAddWorkerMessage extends BusLocalMessage(BusSystemMessage) {
+    worker;
+    constructor(options) {
+        super(options);
+        this.worker = options.worker;
+    }
+}
+/**
+ * Snapshot of workers managed by a runner.
+ *
+ * Sent by the runner on startup and when new runners connect, so that remote
+ * runners can discover each other's workers.
+ */
+export class BusWorkerRegistryMessage extends BusSystemMessage {
+    runner;
+    workers;
+    constructor(options) {
+        super(options);
+        this.runner = options.runner;
+        this.workers = options.workers;
+    }
+}
+/**
+ * Announces that a worker is ready.
+ *
+ * Sent when any worker (root or child) becomes ready. Carries the worker's
+ * parent name so observers can reconstruct the full hierarchy.
+ */
+export class BusWorkerReadyMessage extends BusDataMessage {
+    runner;
+    parent;
+    active;
+    bridged;
+    startedAt;
+    constructor(options) {
+        super(options);
+        this.runner = options.runner;
+        this.parent = options.parent ?? null;
+        this.active = options.active ?? false;
+        this.bridged = options.bridged ?? false;
+        this.startedAt = options.startedAt ?? null;
+    }
+}
+/**
+ * Reports an error from a root worker.
+ *
+ * Sent over the network so remote workers can react. For child worker errors,
+ * see `BusWorkerLocalErrorMessage`.
+ */
+export class BusWorkerErrorMessage extends BusSystemMessage {
+    error;
+    constructor(options) {
+        super(options);
+        this.error = options.error;
+    }
+}
+/**
+ * Reports an error from a child worker to its parent.
+ *
+ * Local-only: never crosses the network. The parent receives it via
+ * `onWorkerFailed()`.
+ */
+export class BusWorkerLocalErrorMessage extends BusLocalMessage(BusSystemMessage) {
+    error;
+    constructor(options) {
+        super(options);
+        this.error = options.error;
+    }
+}
+/** Requests a worker worker to start work. */
+export class BusJobRequestMessage extends BusDataMessage {
+    jobId;
+    jobName;
+    payload;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.jobName = options.jobName ?? null;
+        this.payload = options.payload ?? null;
+    }
+}
+/** Response from a worker worker when its job completes. */
+export class BusJobResponseMessage extends BusDataMessage {
+    jobId;
+    status;
+    response;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.status = options.status;
+        this.response = options.response ?? null;
+    }
+}
+/**
+ * High-priority job response.
+ *
+ * Same semantics as `BusJobResponseMessage` but delivered with system
+ * priority, preempting queued data messages.
+ */
+export class BusJobResponseUrgentMessage extends BusSystemMessage {
+    jobId;
+    status;
+    response;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.status = options.status;
+        this.response = options.response ?? null;
+    }
+}
+/** Progress update from a worker worker. */
+export class BusJobUpdateMessage extends BusDataMessage {
+    jobId;
+    update;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.update = options.update ?? null;
+    }
+}
+/**
+ * High-priority job progress update.
+ *
+ * Same semantics as `BusJobUpdateMessage` but delivered with system priority,
+ * preempting queued data messages.
+ */
+export class BusJobUpdateUrgentMessage extends BusSystemMessage {
+    jobId;
+    update;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.update = options.update ?? null;
+    }
+}
+/** Request a progress update from a worker worker. */
+export class BusJobUpdateRequestMessage extends BusDataMessage {
+    jobId;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+    }
+}
+/** Cancel a running job. */
+export class BusJobCancelMessage extends BusSystemMessage {
+    jobId;
+    reason;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.reason = options.reason ?? null;
+    }
+}
+/** Signals the start of a streaming job response. */
+export class BusJobStreamStartMessage extends BusDataMessage {
+    jobId;
+    /** Optional metadata (e.g. content type). */
+    data;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.data = options.data ?? null;
+    }
+}
+/** A chunk of streaming job data. */
+export class BusJobStreamDataMessage extends BusDataMessage {
+    jobId;
+    /** The chunk payload. */
+    data;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.data = options.data ?? null;
+    }
+}
+/** Signals the end of a streaming job response. */
+export class BusJobStreamEndMessage extends BusDataMessage {
+    jobId;
+    /** Optional final metadata. */
+    data;
+    constructor(options) {
+        super(options);
+        this.jobId = options.jobId;
+        this.data = options.data ?? null;
+    }
+}
+//# sourceMappingURL=messages.js.map

package/dist/bus/network/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Network bus implementations for distributed workers.
+ *
+ * Each adapter has its own optional dependency, so each lives in its own
+ * package and is imported from there:
+ *
+ * - `PgmqBus`: `@pipedog/bus-pgmq/pgmq`
+ * - `RedisBus`: `@pipedog/bus-redis/redis`
+ *
+ * PORTING NOTE: upstream re-exports both names lazily (a module
+ * `__getattr__`) so the package loads with only the extras installed.
+ * ES modules have no lazy re-exports, and a static re-export would make core
+ * depend on both network packages, so this module re-exports nothing.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/bus/network/index.js

@@ -0,0 +1,21 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/bus/network/__init__.py
+/**
+ * Network bus implementations for distributed workers.
+ *
+ * Each adapter has its own optional dependency, so each lives in its own
+ * package and is imported from there:
+ *
+ * - `PgmqBus`: `@pipedog/bus-pgmq/pgmq`
+ * - `RedisBus`: `@pipedog/bus-redis/redis`
+ *
+ * PORTING NOTE: upstream re-exports both names lazily (a module
+ * `__getattr__`) so the package loads with only the extras installed.
+ * ES modules have no lazy re-exports, and a static re-export would make core
+ * depend on both network packages, so this module re-exports nothing.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/bus/queue.d.ts

@@ -0,0 +1,27 @@
+/** Priority queue for bus messages. */
+import { Queue } from "@pipedog/asyncio";
+import { type BusMessage } from "./messages.ts";
+export declare const HIGH_PRIORITY = 1;
+export declare const LOW_PRIORITY = 2;
+/**
+ * Priority queue that delivers system messages before normal messages.
+ *
+ * Messages that extend `BusSystemMessage` (e.g. cancel messages) get high
+ * priority. All other messages are delivered in FIFO order at normal
+ * priority.
+ *
+ * Upstream subclasses `asyncio.PriorityQueue` and wraps each message in a
+ * `(priority, counter, message)` tuple in `put()`/`put_nowait()`, unwrapping
+ * it in `get()`. Here the queue is a `Queue<BusMessage>` whose storage hooks
+ * keep the same tuples in a heap, so `put`, `putNowait`, `get` and
+ * `getNowait` all take and return plain messages.
+ */
+export declare class BusMessageQueue extends Queue<BusMessage> {
+    #private;
+    /** Add a message to the heap with automatic priority assignment. */
+    protected _put(item: BusMessage): void;
+    /** Get the next message, with system messages prioritized. */
+    protected _get(): BusMessage;
+    protected _size(): number;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/bus/queue.js

@@ -0,0 +1,51 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/bus/queue.py
+/** Priority queue for bus messages. */
+import { heapPop, heapPush, Queue } from "@pipedog/asyncio";
+import { BusSystemMessage } from "./messages.js";
+export const HIGH_PRIORITY = 1;
+export const LOW_PRIORITY = 2;
+function compareEntries(a, b) {
+    return a[0] - b[0] || a[1] - b[1];
+}
+/**
+ * Priority queue that delivers system messages before normal messages.
+ *
+ * Messages that extend `BusSystemMessage` (e.g. cancel messages) get high
+ * priority. All other messages are delivered in FIFO order at normal
+ * priority.
+ *
+ * Upstream subclasses `asyncio.PriorityQueue` and wraps each message in a
+ * `(priority, counter, message)` tuple in `put()`/`put_nowait()`, unwrapping
+ * it in `get()`. Here the queue is a `Queue<BusMessage>` whose storage hooks
+ * keep the same tuples in a heap, so `put`, `putNowait`, `get` and
+ * `getNowait` all take and return plain messages.
+ */
+export class BusMessageQueue extends Queue {
+    #heap = [];
+    #highCounter = 0;
+    #lowCounter = 0;
+    /** Add a message to the heap with automatic priority assignment. */
+    _put(item) {
+        if (item instanceof BusSystemMessage) {
+            this.#highCounter += 1;
+            heapPush(this.#heap, [HIGH_PRIORITY, this.#highCounter, item], compareEntries);
+        }
+        else {
+            this.#lowCounter += 1;
+            heapPush(this.#heap, [LOW_PRIORITY, this.#lowCounter, item], compareEntries);
+        }
+    }
+    /** Get the next message, with system messages prioritized. */
+    _get() {
+        const [, , message] = heapPop(this.#heap, compareEntries);
+        return message;
+    }
+    _size() {
+        return this.#heap.length;
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/bus/serializers/base.d.ts

@@ -0,0 +1,25 @@
+/** Abstract base classes for bus message serialization. */
+import type { BusMessage } from "../messages.ts";
+/**
+ * Serialize and deserialize `BusMessage` instances for network transport.
+ *
+ * Network bus implementations use a `MessageSerializer` to convert messages
+ * to bytes for transmission and reconstruct them on the receiving end.
+ */
+export declare abstract class MessageSerializer {
+    /**
+     * Convert a bus message to bytes.
+     *
+     * @param message The bus message to serialize.
+     * @returns The serialized bytes.
+     */
+    abstract serialize(message: BusMessage): Uint8Array;
+    /**
+     * Reconstruct a bus message from bytes.
+     *
+     * @param data The serialized bytes produced by `serialize()`.
+     * @returns The reconstructed `BusMessage`.
+     */
+    abstract deserialize(data: Uint8Array): BusMessage | null;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/bus/serializers/base.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/bus/serializers/base.py
+/**
+ * Serialize and deserialize `BusMessage` instances for network transport.
+ *
+ * Network bus implementations use a `MessageSerializer` to convert messages
+ * to bytes for transmission and reconstruct them on the receiving end.
+ */
+export class MessageSerializer {
+}
+//# sourceMappingURL=base.js.map

package/dist/bus/serializers/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Bus message serialization for network transport.
+ *
+ * Provides the abstract `MessageSerializer` interface and a default
+ * `JSONMessageSerializer` implementation.
+ */
+export { MessageSerializer } from "./base.ts";
+export { JSONMessageSerializer } from "./json.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/bus/serializers/index.js

@@ -0,0 +1,14 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/bus/serializers/__init__.py
+/**
+ * Bus message serialization for network transport.
+ *
+ * Provides the abstract `MessageSerializer` interface and a default
+ * `JSONMessageSerializer` implementation.
+ */
+export { MessageSerializer } from "./base.js";
+export { JSONMessageSerializer } from "./json.js";
+//# sourceMappingURL=index.js.map

package/dist/bus/serializers/json.d.ts

@@ -0,0 +1,77 @@
+import type { Ctor } from "../../utils/mixin.ts";
+import type { TypeAdapter } from "../adapters/base.ts";
+import { type BusMessage } from "../messages.ts";
+import { MessageSerializer } from "./base.ts";
+/** An `as const` enum object: member names mapped to their values. */
+export type EnumObject = Readonly<Record<string, unknown>>;
+/** A type the serializer can name on the wire: a class or an `as const` enum. */
+export type SerializableType = Ctor | EnumObject;
+/**
+ * Register a type under its fully qualified (upstream) name, so it can be
+ * tagged on serialization and resolved on deserialization.
+ *
+ * @param qualifiedName Dotted path like `"pipecat.frames.frames.TextFrame"`.
+ * @param type The class, or the `as const` enum object.
+ */
+export declare function registerSerializableType(qualifiedName: string, type: SerializableType): void;
+/**
+ * Declare that a class field holds a value of an `as const` enum, so the
+ * value is tagged with the enum's name as upstream tags an `Enum` member.
+ * The enum must be registered with `registerSerializableType()`.
+ *
+ * @param type The class declaring the field (subclasses inherit it).
+ * @param field The field's (camelCase) name.
+ * @param enumType The enum object.
+ */
+export declare function registerEnumField(type: Ctor, field: string, enumType: EnumObject): void;
+/**
+ * Serialize bus messages as JSON with pluggable type adapters.
+ *
+ * Handles JSON-native types, enums, bytes, dataclasses, and any type with a
+ * registered `TypeAdapter` (e.g. `LLMContext`, `ToolsSchema`). Adapters for
+ * common Pipecat types are registered by default. Additional type adapters
+ * can be registered via `registerAdapter()`.
+ *
+ * @example
+ * const serializer = new JSONMessageSerializer();
+ *
+ * const data = serializer.serialize(message);
+ * const restored = serializer.deserialize(data);
+ */
+export declare class JSONMessageSerializer extends MessageSerializer {
+    protected _adapters: Map<Ctor, TypeAdapter>;
+    /** Create a serializer with default adapters for `LLMContext` and `ToolsSchema`. */
+    constructor();
+    /**
+     * Register a type adapter.
+     *
+     * @param type The type to handle.
+     * @param adapter The adapter that serializes/deserializes instances of this type.
+     */
+    registerAdapter(type: Ctor, adapter: TypeAdapter): void;
+    /**
+     * Convert a bus message to JSON bytes.
+     *
+     * @param message The bus message to serialize.
+     * @returns UTF-8 encoded JSON bytes.
+     */
+    serialize(message: BusMessage): Uint8Array;
+    /**
+     * Reconstruct a bus message from JSON bytes.
+     *
+     * @param data The JSON bytes produced by `serialize()`.
+     * @returns The reconstructed `BusMessage`, or null if deserialization fails.
+     */
+    deserialize(data: Uint8Array | string): BusMessage | null;
+    /** Recursively serialize a value to a JSON-compatible representation. */
+    protected _serializeValue(value: unknown): unknown;
+    /** Tag a value of an `as const` enum with its member name. */
+    protected _serializeEnum(enumType: EnumObject, value: unknown): unknown;
+    /** Recursively deserialize a value from its JSON representation. */
+    protected _deserializeValue(value: unknown): unknown;
+    /** Deserialize a tagged value using its fully qualified type name. */
+    protected _deserializeTyped(typeName: string, data: unknown): unknown;
+    /** Find an adapter for a type, checking parent classes through the prototype chain. */
+    protected _findAdapter(type: Ctor): TypeAdapter | null;
+}
+//# sourceMappingURL=json.d.ts.map