@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/async_tool_cancellation.js

@@ -0,0 +1,78 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/async_tool_cancellation.py
+/**
+ * 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.js";
+export const ASYNC_TOOL_CANCELLATION_INSTRUCTIONS = `ASYNC TOOL CANCELLATION:
+Some of your tools keep running in the background after you have replied, and some of \
+those can be stopped early.
+
+Work 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.
+
+When 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 — don't just answer.
+
+Call 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 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 function cancelToolName(functionName) {
+    return `${CANCEL_TOOL_PREFIX}${functionName}`;
+}
+/**
+ * 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 function buildCancelToolSchema(functionName) {
+    return new FunctionSchema({
+        name: cancelToolName(functionName),
+        description: `Stop a running ${functionName} call whose result is no longer ` +
+            "needed — the user says to drop it, asks for something that replaces " +
+            "it, or says something that makes the pending result stale. Call it " +
+            "with no arguments to stop the one running call; only when several " +
+            `${functionName} calls are running does it need a tool_call_id to ` +
+            "say which.",
+        properties: {
+            tool_call_id: {
+                type: "string",
+                description: `Which ${functionName} call to stop. Needed only when ` +
+                    "several are running, and carried by the message in the " +
+                    "conversation that reported each one running.",
+            },
+        },
+        required: [],
+    });
+}
+//# sourceMappingURL=async_tool_cancellation.js.map

package/dist/utils/asyncio/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/asyncio/index.js

@@ -0,0 +1,7 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/asyncio/__init__.py
+export {};
+//# sourceMappingURL=index.js.map

package/dist/utils/asyncio/task_manager.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Asyncio task management.
+ *
+ * Provides task management functionality, including abstract base classes and
+ * concrete implementations for managing tasks with monitoring and cleanup.
+ */
+import { type Task, type TaskFn } from "@pipedog/asyncio";
+/** Stand-in for asyncio's event loop: only its clock is used by pipecat. */
+export interface EventLoop {
+    /** Monotonic time in seconds. */
+    time(): number;
+}
+export declare function getRunningLoop(): EventLoop;
+/**
+ * Abstract base class for task management.
+ *
+ * Provides the interface for creating, monitoring, and managing tasks.
+ */
+export declare abstract class BaseTaskManager {
+    /** Get the event loop used by this task manager. */
+    abstract getEventLoop(): EventLoop;
+    /**
+     * Creates and schedules a new task that runs the given coroutine function.
+     * The task is added to the set of created tasks.
+     */
+    abstract createTask<T>(coroutine: TaskFn<T>, name: string): Task<T | undefined>;
+    /**
+     * Cancels the given task and awaits its completion with an optional timeout
+     * (seconds). Cancelling the task this call runs on is logged and ignored.
+     */
+    abstract cancelTask(task: Task<unknown>, timeout?: number | null): Promise<void>;
+    /** Returns the list of currently created/registered tasks. */
+    abstract currentTasks(): readonly Task<unknown>[];
+}
+/**
+ * Concrete implementation of BaseTaskManager. Manages task lifecycle
+ * including creation, monitoring, cancellation, and cleanup.
+ */
+export declare class TaskManager extends BaseTaskManager {
+    #private;
+    constructor(options?: {
+        loop?: EventLoop;
+    });
+    getEventLoop(): EventLoop;
+    createTask<T>(coroutine: TaskFn<T>, name: string): Task<T | undefined>;
+    cancelTask(task: Task<unknown>, timeout?: number | null): Promise<void>;
+    currentTasks(): readonly Task<unknown>[];
+}
+//# sourceMappingURL=task_manager.d.ts.map

package/dist/utils/asyncio/task_manager.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/asyncio/task_manager.py
+/**
+ * Asyncio task management.
+ *
+ * Provides task management functionality, including abstract base classes and
+ * concrete implementations for managing tasks with monitoring and cleanup.
+ */
+import { CancelledError, createTask, currentTask, monotonic, TimeoutError, waitFor, } from "@pipedog/asyncio";
+import { logger } from "../logger.js";
+const defaultLoop = { time: monotonic };
+export function getRunningLoop() {
+    return defaultLoop;
+}
+/**
+ * Abstract base class for task management.
+ *
+ * Provides the interface for creating, monitoring, and managing tasks.
+ */
+export class BaseTaskManager {
+}
+/**
+ * Concrete implementation of BaseTaskManager. Manages task lifecycle
+ * including creation, monitoring, cancellation, and cleanup.
+ */
+export class TaskManager extends BaseTaskManager {
+    #loop;
+    #tasks = new Set();
+    constructor(options = {}) {
+        super();
+        this.#loop = options.loop ?? getRunningLoop();
+    }
+    getEventLoop() {
+        return this.#loop;
+    }
+    createTask(coroutine, name) {
+        const runCoroutine = async () => {
+            try {
+                return await coroutine();
+            }
+            catch (e) {
+                if (e instanceof CancelledError) {
+                    logger.trace(`${name}: task cancelled`);
+                    // Re-raise the exception to ensure the task is cancelled.
+                    throw e;
+                }
+                logger.error(`${name} unexpected exception: ${errorMessage(e)}`, e);
+                return undefined;
+            }
+        };
+        const task = createTask(runCoroutine, name);
+        task.addDoneCallback((t) => this.#taskDoneHandler(t));
+        this.#tasks.add(task);
+        logger.trace(`${name}: task created`);
+        return task;
+    }
+    async cancelTask(task, timeout = null) {
+        const name = task.getName();
+        const current = currentTask();
+        if (task === current) {
+            logger.warning(`${name}: ignoring attempt to cancel the running task`);
+            return;
+        }
+        const cancelsRequested = current ? current.cancelling() : 0;
+        task.cancel();
+        try {
+            if (timeout) {
+                await waitFor(task, timeout);
+            }
+            else {
+                await task;
+            }
+        }
+        catch (e) {
+            if (e instanceof TimeoutError) {
+                logger.warning(`${name}: timed out waiting for task to cancel`);
+            }
+            else if (e instanceof CancelledError) {
+                // Either `task` finished cancelling, or the calling task was
+                // cancelled while we waited. Only the latter may propagate.
+                if (current && current.cancelling() > cancelsRequested) {
+                    throw e;
+                }
+            }
+            else {
+                logger.error(`${name} unexpected exception while cancelling task: ${errorMessage(e)}`, e);
+            }
+        }
+    }
+    currentTasks() {
+        return [...this.#tasks];
+    }
+    #taskDoneHandler(task) {
+        if (!this.#tasks.delete(task)) {
+            logger.trace(`${task.getName()}: unable to remove task data (already removed?)`);
+        }
+    }
+}
+function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+//# sourceMappingURL=task_manager.js.map

package/dist/utils/base_object.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Base object class providing event handling and lifecycle management.
+ *
+ * Offers unique identification, naming, event handling, and async cleanup for
+ * all Pipecat components.
+ */
+import { type Task, type TaskFn } from "@pipedog/asyncio";
+import type { BaseTaskManager } from "./asyncio/task_manager.ts";
+export type EventHandlerFn<Self = any> = (self: Self, ...args: any[]) => unknown;
+/** Stores an event name, its handlers, and whether they run inline (sync). */
+export interface EventHandler {
+    name: string;
+    handlers: EventHandlerFn[];
+    isSync: boolean;
+}
+export interface BaseObjectOptions {
+    /** Custom name; defaults to `ClassName#count`. */
+    name?: string | null;
+    /** Task manager for handling tasks. */
+    taskManager?: BaseTaskManager | null;
+}
+/**
+ * Abstract base class providing common functionality for Pipecat objects:
+ * unique identification, naming, event handling and async lifecycle.
+ */
+export declare abstract class BaseObject {
+    protected _id: number;
+    protected _name: string;
+    protected _taskManager: BaseTaskManager | null;
+    protected _eventHandlers: Map<string, EventHandler>;
+    protected _eventTasks: Set<[string, Task<unknown>]>;
+    constructor(options?: BaseObjectOptions);
+    /** The unique identifier for this object. */
+    get id(): number;
+    /** The object's name, either custom-provided or auto-generated. */
+    get name(): string;
+    /** The task manager. Throws if not initialized. */
+    get taskManager(): BaseTaskManager;
+    /**
+     * Wire the object up with a task manager. Owners of a BaseObject should
+     * call this on their child objects to propagate the task manager down.
+     */
+    setup(taskManager: BaseTaskManager | unknown): Promise<void>;
+    /** Create a new task managed by this object's task manager. */
+    createTask<T>(coroutine: TaskFn<T>, name?: string | null): Task<T | undefined>;
+    /**
+     * Cancel a task managed by this object's task manager. A default timeout of
+     * 1 second avoids freezes caused by code that swallows cancellation.
+     */
+    cancelTask(task: Task<unknown>, timeout?: number | null): Promise<void>;
+    /**
+     * Clean up resources and wait for running event handlers to complete,
+     * except the one it is called from, since a task can't wait for itself.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Register a handler for an event. Equivalent of Python's
+     * `@obj.event_handler("on_x")` decorator; returns the handler.
+     */
+    eventHandler<F extends EventHandlerFn<this>>(eventName: string, handler: F): F;
+    /** Add an event handler for the specified event. Can be sync or async. */
+    addEventHandler(eventName: string, handler: EventHandlerFn<this>): void;
+    /** Remove a previously added event handler. No-op if unknown. */
+    removeEventHandler(eventName: string, handler: EventHandlerFn<this>): void;
+    /**
+     * Register an event handler type.
+     *
+     * @param sync Whether handlers run inline (awaited) instead of in a task.
+     */
+    protected _registerEventHandler(eventName: string, sync?: boolean): void;
+    /** Call all registered handlers for the specified event. */
+    protected _callEventHandler(eventName: string, ...args: any[]): Promise<void>;
+    protected _runHandler(eventName: string, handler: EventHandlerFn, ...args: any[]): Promise<void>;
+    toString(): string;
+}
+//# sourceMappingURL=base_object.d.ts.map

package/dist/utils/base_object.js

@@ -0,0 +1,154 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/base_object.py
+/**
+ * Base object class providing event handling and lifecycle management.
+ *
+ * Offers unique identification, naming, event handling, and async cleanup for
+ * all Pipecat components.
+ */
+import { createTask, currentTask, rethrowIfCancelled, wait, } from "@pipedog/asyncio";
+import { logger } from "./logger.js";
+import { objCount, objId } from "./utils.js";
+/**
+ * Abstract base class providing common functionality for Pipecat objects:
+ * unique identification, naming, event handling and async lifecycle.
+ */
+export class BaseObject {
+    _id;
+    _name;
+    _taskManager;
+    // Registered event handlers.
+    _eventHandlers = new Map();
+    // Event handler tasks being executed; removed when they finish. Cleanup
+    // waits for those still running.
+    _eventTasks = new Set();
+    constructor(options = {}) {
+        this._id = objId();
+        this._name = options.name || `${this.constructor.name}#${objCount(this)}`;
+        this._taskManager = options.taskManager ?? null;
+    }
+    /** The unique identifier for this object. */
+    get id() {
+        return this._id;
+    }
+    /** The object's name, either custom-provided or auto-generated. */
+    get name() {
+        return this._name;
+    }
+    /** The task manager. Throws if not initialized. */
+    get taskManager() {
+        if (!this._taskManager) {
+            throw new Error(`${this}: TaskManager is not initialized.`);
+        }
+        return this._taskManager;
+    }
+    /**
+     * Wire the object up with a task manager. Owners of a BaseObject should
+     * call this on their child objects to propagate the task manager down.
+     */
+    // Typed `unknown` so subclasses can narrow it (FrameProcessor.setup takes a
+    // FrameProcessorSetup, as upstream does).
+    async setup(taskManager) {
+        this._taskManager = taskManager;
+    }
+    /** Create a new task managed by this object's task manager. */
+    createTask(coroutine, name) {
+        const taskName = name || coroutine.name || "task";
+        return this.taskManager.createTask(coroutine, `${this}::${taskName}`);
+    }
+    /**
+     * Cancel a task managed by this object's task manager. A default timeout of
+     * 1 second avoids freezes caused by code that swallows cancellation.
+     */
+    async cancelTask(task, timeout = 1.0) {
+        await this.taskManager.cancelTask(task, timeout);
+    }
+    /**
+     * Clean up resources and wait for running event handlers to complete,
+     * except the one it is called from, since a task can't wait for itself.
+     */
+    async cleanup() {
+        const current = currentTask();
+        const eventTasks = [...this._eventTasks].filter(([, task]) => task !== current);
+        if (eventTasks.length > 0) {
+            const names = eventTasks.map(([name]) => name);
+            logger.debug(`${this}: waiting on event handlers to finish [${names.join(", ")}]...`);
+            await wait(eventTasks.map(([, task]) => task));
+        }
+    }
+    /**
+     * Register a handler for an event. Equivalent of Python's
+     * `@obj.event_handler("on_x")` decorator; returns the handler.
+     */
+    eventHandler(eventName, handler) {
+        this.addEventHandler(eventName, handler);
+        return handler;
+    }
+    /** Add an event handler for the specified event. Can be sync or async. */
+    addEventHandler(eventName, handler) {
+        const eventHandler = this._eventHandlers.get(eventName);
+        if (eventHandler) {
+            eventHandler.handlers.push(handler);
+        }
+        else {
+            logger.warning(`${this}: event handler ${eventName} not registered`);
+        }
+    }
+    /** Remove a previously added event handler. No-op if unknown. */
+    removeEventHandler(eventName, handler) {
+        const eventHandler = this._eventHandlers.get(eventName);
+        if (!eventHandler)
+            return;
+        const index = eventHandler.handlers.indexOf(handler);
+        if (index >= 0)
+            eventHandler.handlers.splice(index, 1);
+    }
+    /**
+     * Register an event handler type.
+     *
+     * @param sync Whether handlers run inline (awaited) instead of in a task.
+     */
+    _registerEventHandler(eventName, sync = false) {
+        if (!this._eventHandlers.has(eventName)) {
+            this._eventHandlers.set(eventName, { name: eventName, handlers: [], isSync: sync });
+        }
+        else {
+            logger.warning(`${this}: event handler ${eventName} already registered`);
+        }
+    }
+    /** Call all registered handlers for the specified event. */
+    async _callEventHandler(eventName, ...args) {
+        const eventHandler = this._eventHandlers.get(eventName);
+        if (!eventHandler)
+            return;
+        for (const handler of eventHandler.handlers) {
+            if (eventHandler.isSync) {
+                await this._runHandler(eventHandler.name, handler, ...args);
+            }
+            else {
+                // A task per handler function. Users can register to an event
+                // handler multiple times.
+                const task = createTask(() => this._runHandler(eventHandler.name, handler, ...args));
+                const entry = [eventName, task];
+                this._eventTasks.add(entry);
+                task.addDoneCallback(() => this._eventTasks.delete(entry));
+            }
+        }
+    }
+    async _runHandler(eventName, handler, ...args) {
+        try {
+            await handler(this, ...args);
+        }
+        catch (e) {
+            rethrowIfCancelled(e);
+            logger.error(`${this}: uncaught exception in event handler '${eventName}': ${e instanceof Error ? e.message : e}`, e);
+        }
+    }
+    toString() {
+        return this.name;
+    }
+}
+//# sourceMappingURL=base_object.js.map