@pipedog/core 0.0.0 → 0.2.0

package/dist/workers/base_worker.js

@@ -0,0 +1,1298 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/workers/base_worker.py
+/**
+ * Abstract base worker for the multi-worker framework.
+ *
+ * Provides the `BaseWorker` class that all workers inherit from, handling
+ * worker lifecycle, parent-child relationships, and long-running job
+ * coordination on the bus.
+ *
+ * Porting notes:
+ * - The deprecated per-argument job spelling (`name=`, `payload=`,
+ *   `timeout=`, `cancel_on_error=` on `request_job`, `job`,
+ *   `request_job_group`, `job_group` and `create_job_group_and_request_job`)
+ *   and `resolve_job_params` are not ported; pass `params` instead.
+ * - Methods that take `*names` plus keyword arguments take the names as rest
+ *   arguments and an optional trailing options object:
+ *   `this.jobGroup("w1", "w2", { params })`, `this.addWorkers(a, b, { watch: false })`.
+ */
+import { CancelledError, currentTask, Event, gather, Lock, sleep, TimeoutError, time, waitFor, } from "@pipedog/asyncio";
+import { BusActivateWorkerMessage, BusAddWorkerMessage, BusCancelMessage, BusCancelWorkerMessage, BusDeactivateWorkerMessage, BusEndMessage, BusEndWorkerMessage, BusFrameMessage, BusJobCancelMessage, BusJobRequestMessage, BusJobResponseMessage, BusJobResponseUrgentMessage, BusJobStreamDataMessage, BusJobStreamEndMessage, BusJobStreamStartMessage, BusJobUpdateMessage, BusJobUpdateRequestMessage, BusJobUpdateUrgentMessage, BusWorkerErrorMessage, BusWorkerLocalErrorMessage, BusWorkerReadyMessage, } from "../bus/messages.js";
+import { BusSubscriber } from "../bus/subscriber.js";
+import { JobContext, JobGroup, JobGroupContext, JobGroupError, JobGroupEvent, JobGroupParams, JobGroupResponse, JobParams, JobStatus, } from "../pipeline/job_context.js";
+import { _collectJobHandlers } from "../pipeline/job_decorator.js";
+import { _collectWorkerReadyHandlers } from "../pipeline/worker_ready_decorator.js";
+import { WorkerErrorData, WorkerReadyData } from "../registry/types.js";
+import { BaseObject } from "../utils/base_object.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Configuration parameters for worker execution.
+ *
+ * - `taskManager`: Task manager for handling asyncio tasks.
+ */
+export class WorkerParams {
+    taskManager;
+    constructor(options) {
+        this.taskManager = options.taskManager;
+    }
+}
+/**
+ * Base activation arguments for any worker.
+ *
+ * - `metadata`: Optional structured data passed during activation.
+ *
+ * Subclasses add fields (with defaults) and accept them in their options
+ * object; `fromDict` and `toDict` work off the instance's own fields.
+ */
+export class WorkerActivationArgs {
+    metadata;
+    constructor(options = {}) {
+        this.metadata = options.metadata ?? null;
+    }
+    /** Create from a dict, ignoring unknown keys. */
+    static fromDict(data) {
+        const fields = new Set(Object.keys(new this({})));
+        return new this(Object.fromEntries(Object.entries(data).filter(([k]) => fields.has(k))));
+    }
+    /** Convert to a dict, excluding null values. */
+    toDict() {
+        return Object.fromEntries(Object.entries(this).filter(([, value]) => value !== null && value !== undefined));
+    }
+}
+/**
+ * Messages an inactive worker still receives: the ones that change whether it
+ * is active, and the ones that stop it. Gating these would leave it with no
+ * way to be woken or shut down.
+ */
+const ALWAYS_DELIVERED = [
+    BusActivateWorkerMessage,
+    BusDeactivateWorkerMessage,
+    BusEndWorkerMessage,
+    BusCancelWorkerMessage,
+];
+/** Split `(...names, options?)` rest arguments. */
+function splitTrailingOptions(args, isItem) {
+    const last = args[args.length - 1];
+    if (args.length > 0 && !isItem(last) && typeof last === "object" && last !== null) {
+        return [args.slice(0, -1), last];
+    }
+    return [args, {}];
+}
+function checkWorkerNames(worker, workerNames) {
+    for (const workerName of workerNames) {
+        if (typeof workerName !== "string") {
+            const typeName = workerName === null
+                ? "NoneType"
+                : typeof workerName === "object"
+                    ? workerName.constructor.name
+                    : typeof workerName;
+            throw new TypeError(`${worker} Expected worker name as str, got ${typeName}`);
+        }
+    }
+}
+/**
+ * Abstract base for workers in framework.
+ *
+ * A worker connects to a `WorkerBus`, registers itself in the shared
+ * registry, accepts activation/deactivation, and exchanges job
+ * requests/responses with other workers. Concrete subclasses
+ * (e.g. `PipelineWorker`) provide the runtime that actually drives
+ * the worker's work.
+ *
+ * Overridable lifecycle methods (always call `super`):
+ *
+ * - `onActivated(args)`: Called when this worker is activated.
+ * - `onDeactivated()`: Called when this worker is deactivated.
+ * - `onWorkerReady(data)`: Called when another worker is ready to receive
+ *   messages. For local root workers, fires automatically. For children,
+ *   fires only on the parent. For remote workers, fires only for workers
+ *   watched via `watchWorkers()`.
+ * - `onJobRequest(message)`: Called when a job request is received.
+ * - `onJobResponse(message)`: Called when a worker sends a response.
+ * - `onJobUpdate(message)`: Called when a worker sends a progress update.
+ * - `onJobUpdateRequested(message)`: Called when the requester asks for a
+ *   progress update.
+ * - `onJobCompleted(result)`: Called when all workers in a job group have
+ *   responded.
+ * - `onJobError(message)`: Called when a worker errors and the group is
+ *   cancelled (`cancelOnError`).
+ * - `onJobStreamStart(message)`: Called when a worker begins streaming.
+ * - `onJobStreamData(message)`: Called for each streaming chunk from a worker.
+ * - `onJobStreamEnd(message)`: Called when a worker finishes streaming.
+ * - `onJobCancelled(message)`: Called when this worker's job is cancelled by
+ *   the requester.
+ * - `onBusMessage(message)`: Called for bus messages after default lifecycle
+ *   handling.
+ *
+ * Event handlers available:
+ *
+ * - on_activated: Worker was activated.
+ * - on_deactivated: Worker was deactivated.
+ * - on_worker_ready: Another worker is ready.
+ * - on_worker_failed: A child worker reported an error.
+ * - on_job_request: Received a job request.
+ * - on_job_response: A worker sent a response.
+ * - on_job_update: A worker sent a progress update.
+ * - on_job_update_requested: Requester asked for a progress update.
+ * - on_job_completed: All workers in a job group responded.
+ * - on_job_error: A worker errored and the group was cancelled.
+ * - on_job_stream_start: A worker started streaming.
+ * - on_job_stream_data: A worker sent a streaming chunk.
+ * - on_job_stream_end: A worker finished streaming.
+ * - on_job_cancelled: This worker's job was cancelled.
+ * - on_bus_message: A bus message was received.
+ */
+export class BaseWorker extends BusSubscriber(BaseObject) {
+    // Only the owner of a task manager reports its dangling tasks. A worker
+    // that's handed its own task manager owns it; one that falls back to the
+    // runner's shared task manager does not (the runner reports instead).
+    _checkDanglingTasks;
+    _ownsTaskManager;
+    // Runner-provided context. Populated by `attach()` before `run()` is
+    // called. Accessing `this.bus` / `this.registry` before `attach()` throws.
+    _bus = null;
+    _registry = null;
+    _workerRunner = null;
+    // Activation. Pending activation is deferred until the worker starts, then
+    // onActivated fires.
+    _active;
+    _pendingActivation;
+    _activationArgs = null;
+    // Worker lifecycle. Parent/children form a tree. Finished is set when the
+    // worker stops.
+    _parent = null;
+    _children = [];
+    _startedAt = null;
+    _finishedEvent = new Event();
+    // Job coordination. Worker state tracks active job requests keyed by
+    // jobId, supporting multiple jobs in flight (e.g. parallel job handlers).
+    // Each running handler has a tracked task so it can be cancelled by system
+    // messages. Requester state tracks job groups launched by this worker. Job
+    // handlers are collected from `job()` decorated methods at init.
+    _activeJobs = new Map();
+    _jobHandlerTasks = new Map();
+    _jobGroups = new Map();
+    _jobHandlers;
+    _jobLocks = new Map();
+    // Worker-ready handlers collected from `workerReady()` decorated methods.
+    _workerReadyHandlers;
+    // A stable handler for registry watches (the registry ignores a handler it
+    // already holds, as Python's bound-method equality does).
+    _onWatchedWorkerReadyHandler = (data) => this._onWatchedWorkerReady(data);
+    /** Initialize the BaseWorker. */
+    constructor(options = {}) {
+        super(options);
+        this._checkDanglingTasks = options.checkDanglingTasks ?? true;
+        this._ownsTaskManager = options.taskManager !== undefined && options.taskManager !== null;
+        this._active = options.active ?? true;
+        this._pendingActivation = this._active;
+        this._jobHandlers = _collectJobHandlers(this);
+        this._workerReadyHandlers = _collectWorkerReadyHandlers(this);
+        // Worker lifecycle events
+        this._registerEventHandler("on_activated");
+        this._registerEventHandler("on_deactivated");
+        this._registerEventHandler("on_bus_message");
+        this._registerEventHandler("on_job_request");
+        this._registerEventHandler("on_job_response");
+        this._registerEventHandler("on_job_update");
+        this._registerEventHandler("on_job_update_requested");
+        this._registerEventHandler("on_job_completed");
+        this._registerEventHandler("on_job_error");
+        this._registerEventHandler("on_job_stream_start");
+        this._registerEventHandler("on_job_stream_data");
+        this._registerEventHandler("on_job_stream_end");
+        this._registerEventHandler("on_job_cancelled");
+        // Other workers
+        this._registerEventHandler("on_worker_ready");
+        this._registerEventHandler("on_worker_failed");
+    }
+    /**
+     * The bus this worker is attached to.
+     *
+     * @throws Error If accessed before `attach()` has been called.
+     */
+    get bus() {
+        if (this._bus === null) {
+            throw new Error(`Worker '${this}': bus is not set; call attach() first.`);
+        }
+        return this._bus;
+    }
+    /**
+     * Whether this worker is accepting bus messages.
+     *
+     * An active worker takes everything addressed to it. An inactive one takes
+     * only activation, deactivation, end or cancel messages, so no job request,
+     * frame or UI event reaches it and none of its `onBusMessage` handling runs.
+     *
+     * It matters mainly in multi-worker setups, where a worker is put out of
+     * the way while the others carry on.
+     *
+     * Registry watches sit outside this: `workerReady` handlers fire from
+     * `WorkerRegistry` whatever this returns, because they never travel over
+     * the bus.
+     */
+    get active() {
+        return this._active;
+    }
+    /** The arguments from the most recent activation, or null if inactive. */
+    get activationArgs() {
+        return this._activationArgs;
+    }
+    /** The name of the parent worker, or null if this is a root worker. */
+    get parent() {
+        return this._parent;
+    }
+    /**
+     * The shared worker registry this worker is attached to.
+     *
+     * @throws Error If accessed before `attach()` has been called.
+     */
+    get registry() {
+        if (this._registry === null) {
+            throw new Error(`Worker '${this}': registry is not set; call attach() first.`);
+        }
+        return this._registry;
+    }
+    /**
+     * The runner this worker is attached to.
+     *
+     * Use it to reach another worker on the same runner by name, e.g.
+     * `this.workerRunner.getWorker("ui-jobs")`.
+     *
+     * @throws Error If accessed before `attach()` has been called.
+     */
+    get workerRunner() {
+        if (this._workerRunner === null) {
+            throw new Error(`Worker '${this}': runner is not set; call attach() first.`);
+        }
+        return this._workerRunner;
+    }
+    /** Unix timestamp (seconds) when this worker became ready, or null if not yet started. */
+    get startedAt() {
+        return this._startedAt;
+    }
+    /**
+     * Whether this worker is bridged onto the bus.
+     *
+     * Subclasses (e.g. `PipelineWorker`) override when they auto-wrap their
+     * pipeline with bus edge processors.
+     */
+    get bridged() {
+        return false;
+    }
+    /** The list of child workers added via `addWorkers()`. */
+    get children() {
+        return this._children;
+    }
+    /** Active job requests this worker is currently working on, keyed by jobId. */
+    get activeJobs() {
+        return this._activeJobs;
+    }
+    /** Active job groups launched by this worker, keyed by jobId. */
+    get jobGroups() {
+        return this._jobGroups;
+    }
+    /**
+     * Attach the worker to a runner-provided registry and bus.
+     *
+     * Called by the runner (typically from `addWorkers()`) before the worker
+     * is run. After this call, `registry` and `bus` return the provided
+     * instances, and the worker is subscribed to the bus — so workers added
+     * later are listening before any worker emits its first message.
+     */
+    async attach(options) {
+        this._registry = options.registry;
+        this._bus = options.bus;
+        this._workerRunner = options.workerRunner;
+        await this._bus.subscribe(this);
+    }
+    /**
+     * Clean up the worker and release resources.
+     *
+     * Cancels running jobs, unsubscribes from the bus, and signals that the
+     * worker has stopped.
+     */
+    async cleanup() {
+        await super.cleanup();
+        await this.stop();
+    }
+    /**
+     * Run this worker until it finishes.
+     *
+     * The default implementation is for bus-only workers: it subscribes to the
+     * bus, marks the worker as started, then waits until `stop()` (or
+     * `_finishedEvent`) is signalled. Subclasses with their own runtime (e.g.
+     * `PipelineWorker`) override this method.
+     *
+     * @param params Configuration parameters for worker execution.
+     */
+    async run(params) {
+        await super.setup(this._taskManager ?? params.taskManager);
+        await this.start();
+        try {
+            await this._finishedEvent.wait();
+        }
+        catch (e) {
+            if (!(e instanceof CancelledError))
+                throw e;
+        }
+        finally {
+            await this.stop();
+            this._printDanglingTasks();
+        }
+    }
+    /** Mark the worker as started, register, and activate if requested. */
+    async start() {
+        this._startedAt = time();
+        await this._registerReady();
+        await this._maybeActivate();
+        await this._watchDecoratedWorkers();
+    }
+    /**
+     * Clean up and signal that this worker has stopped.
+     *
+     * Cancels all running job groups and reports any still-active job
+     * requests back to their requesters as `CANCELLED`, so parents aren't left
+     * waiting, and cancels the handlers still running for them, such as one
+     * holding a long-lived job open.
+     */
+    async stop() {
+        for (const jobId of [...this._jobGroups.keys()]) {
+            await this.cancelJobGroup(jobId, { reason: `worker '${this}' stopped` });
+        }
+        for (const jobId of [...this._activeJobs.keys()]) {
+            await this.sendJobResponse(jobId, null, { status: JobStatus.CANCELLED });
+        }
+        // Cancel every handler still running, including any that may have
+        // already responded (so are no longer in `_activeJobs`) but live on for
+        // some reason.
+        for (const task of [...this._jobHandlerTasks.values()]) {
+            await this.cancelTask(task);
+        }
+        this._finishedEvent.set();
+    }
+    /**
+     * Request a graceful end of the session.
+     *
+     * @param options.reason Optional human-readable reason for ending.
+     */
+    async end(options = {}) {
+        await this.sendBusMessage(new BusEndMessage({ source: this.name, reason: options.reason }));
+    }
+    /**
+     * Request an immediate cancellation of all workers.
+     *
+     * @param options.reason Optional human-readable reason. Propagated through
+     *   the runner to every root worker's `BusCancelWorkerMessage`.
+     */
+    async cancel(options = {}) {
+        await this.sendBusMessage(new BusCancelMessage({ source: this.name, reason: options.reason }));
+    }
+    /** Wait for this worker to finish. */
+    async wait() {
+        await this._finishedEvent.wait();
+    }
+    /**
+     * Called when this worker is activated.
+     *
+     * Override in subclasses to react to activation. Always call
+     * `super.onActivated(args)`.
+     *
+     * @param args Optional arguments from the caller.
+     */
+    async onActivated(_args) { }
+    /**
+     * Called when this worker is deactivated.
+     *
+     * Override in subclasses to react to deactivation. Always call
+     * `super.onDeactivated()`.
+     */
+    async onDeactivated() { }
+    /**
+     * Called when another worker is ready to receive messages.
+     *
+     * For local root workers this fires automatically. For remote workers it
+     * fires only for workers watched via `watchWorkers()`. For child workers
+     * it fires only on the parent that created them.
+     *
+     * @param data Information about the ready worker.
+     */
+    async onWorkerReady(_data) { }
+    /**
+     * Called when a child worker reports an error.
+     *
+     * @param data Information about the error.
+     */
+    async onWorkerFailed(_data) { }
+    /**
+     * Take bus messages only while active.
+     *
+     * An inactive worker is handed only activation, deactivation, end or
+     * cancel messages. Work addressed to it, and everything it would merely
+     * observe, is dropped by the bus rather than reaching `onBusMessage`.
+     *
+     * Registry notifications are unaffected, since `workerReady` watches fire
+     * from `WorkerRegistry` rather than travelling over the bus.
+     *
+     * @param message The bus message about to be delivered.
+     * @returns Whether to deliver the message.
+     */
+    acceptsBusMessage(message) {
+        return this._active || ALWAYS_DELIVERED.some((cls) => message instanceof cls);
+    }
+    /**
+     * Called for every bus message after built-in lifecycle handling.
+     *
+     * Override to handle custom message types. Built-in message types
+     * (activation, end, cancel, job) are already dispatched to their
+     * respective hooks before this method is called.
+     *
+     * @param message The `BusMessage` to process.
+     */
+    async onBusMessage(message) {
+        // Frame messages are not handled by the base worker.
+        if (message instanceof BusFrameMessage) {
+            return;
+        }
+        // Ignore targeted messages for other workers
+        if (message.target && message.target !== this.name) {
+            return;
+        }
+        if (message instanceof BusWorkerErrorMessage || message instanceof BusWorkerLocalErrorMessage) {
+            await this._handleWorkerError(message);
+        }
+        else if (message instanceof BusActivateWorkerMessage) {
+            await this._handleWorkerActivate(message);
+        }
+        else if (message instanceof BusDeactivateWorkerMessage) {
+            await this._handleWorkerDeactivate(message);
+        }
+        else if (message instanceof BusEndWorkerMessage) {
+            await this._handleWorkerEnd(message);
+        }
+        else if (message instanceof BusCancelWorkerMessage) {
+            await this._handleWorkerCancel(message);
+        }
+        else if (message instanceof BusJobRequestMessage) {
+            await this._handleJobRequest(message);
+        }
+        else if (message instanceof BusJobResponseMessage ||
+            message instanceof BusJobResponseUrgentMessage) {
+            await this._handleJobResponse(message);
+        }
+        else if (message instanceof BusJobUpdateMessage ||
+            message instanceof BusJobUpdateUrgentMessage) {
+            await this._handleJobUpdate(message);
+        }
+        else if (message instanceof BusJobUpdateRequestMessage) {
+            await this._handleJobUpdateRequest(message);
+        }
+        else if (message instanceof BusJobCancelMessage) {
+            await this._handleJobCancel(message);
+        }
+        else if (message instanceof BusJobStreamStartMessage) {
+            await this._handleJobStreamStart(message);
+        }
+        else if (message instanceof BusJobStreamDataMessage) {
+            await this._handleJobStreamData(message);
+        }
+        else if (message instanceof BusJobStreamEndMessage) {
+            await this._handleJobStreamEnd(message);
+        }
+        await this._callEventHandler("on_bus_message", message);
+    }
+    /**
+     * Called when this worker receives a job request.
+     *
+     * Override to perform work. Use `sendJobUpdate()` to report progress and
+     * `sendJobResponse()` to return results.
+     */
+    async onJobRequest(_message) { }
+    /**
+     * Called when a worker sends a response.
+     *
+     * Override to process individual results as they arrive.
+     */
+    async onJobResponse(_message) { }
+    /** Called when a worker sends a progress update. */
+    async onJobUpdate(_message) { }
+    /**
+     * Called when the requester asks for a progress update.
+     *
+     * Override to send back a progress update via `sendJobUpdate()`.
+     */
+    async onJobUpdateRequested(_message) { }
+    /** Called when all workers in a job group have responded. */
+    async onJobCompleted(_result) { }
+    /**
+     * Called when a job group is cancelled due to a worker error.
+     *
+     * Fires when a worker responds with `ERROR` or `FAILED` status and
+     * `cancelOnError` is set. The group is cancelled and `onJobCompleted`
+     * will not fire. Partial responses from workers that completed before the
+     * error are available in the job group's `responses`.
+     */
+    async onJobError(_message) { }
+    /** Called when a worker begins streaming. */
+    async onJobStreamStart(_message) { }
+    /** Called for each streaming chunk from a worker. */
+    async onJobStreamData(_message) { }
+    /** Called when a worker finishes streaming. */
+    async onJobStreamEnd(_message) { }
+    /**
+     * Called when this worker's job is cancelled by the requester.
+     *
+     * Override to clean up resources or stop in-progress work.
+     */
+    async onJobCancelled(_message) { }
+    /**
+     * Send a message on the bus.
+     *
+     * @param message The `BusMessage` to send.
+     */
+    async sendBusMessage(message) {
+        if (this._bus) {
+            await this._bus.send(message);
+        }
+    }
+    /**
+     * Report an error on the bus.
+     *
+     * Child workers send a local-only message to the parent. Root workers
+     * broadcast over the network.
+     *
+     * @param error Description of the error.
+     */
+    async sendBusErrorMessage(error) {
+        if (this._parent) {
+            await this.sendBusMessage(new BusWorkerLocalErrorMessage({ source: this.name, error }));
+        }
+        else {
+            await this.sendBusMessage(new BusWorkerErrorMessage({ source: this.name, error }));
+        }
+    }
+    async addWorkers(...args) {
+        const [workers, options] = splitTrailingOptions(args, (v) => v instanceof BaseWorker);
+        const watch = options.watch ?? true;
+        const addedNames = [];
+        for (const worker of workers) {
+            if (worker._parent !== null) {
+                logger.warning(`Worker '${worker.name}' already has parent '${worker._parent}', skipping`);
+                continue;
+            }
+            worker._parent = this.name;
+            this._children.push(worker);
+            addedNames.push(worker.name);
+            await this.sendBusMessage(new BusAddWorkerMessage({ source: this.name, worker }));
+        }
+        if (watch && addedNames.length > 0) {
+            await this.watchWorkers(...addedNames);
+        }
+    }
+    /**
+     * Activate a worker by name.
+     *
+     * The target worker's `onActivated` hook will be called with the provided
+     * arguments. The target need not be active already: an activation reaches
+     * an inactive worker, which is what lets it become active.
+     *
+     * @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.
+     */
+    async activateWorker(workerName, options = {}) {
+        const args = options.args ?? null;
+        const deactivateSelf = options.deactivateSelf ?? false;
+        if (this._active && deactivateSelf) {
+            // Deactivate immediately (don't wait for the bus round-trip) so this
+            // worker and the target are never briefly active at the same time.
+            this._active = false;
+            await this.deactivateWorker(this.name);
+        }
+        await this.sendBusMessage(new BusActivateWorkerMessage({
+            source: this.name,
+            target: workerName,
+            args: args ? args.toDict() : null,
+        }));
+    }
+    /**
+     * Deactivate a worker by name.
+     *
+     * The target worker's `onDeactivated` hook will be called.
+     *
+     * @param workerName The name of the worker to deactivate.
+     */
+    async deactivateWorker(workerName) {
+        await this.sendBusMessage(new BusDeactivateWorkerMessage({ source: this.name, target: workerName }));
+    }
+    /**
+     * Request notification when one or more workers register.
+     *
+     * For each name: if the worker is already registered, `onWorkerReady`
+     * fires immediately. Otherwise `onWorkerReady` fires when the worker
+     * eventually registers.
+     *
+     * @param workerNames Names of workers to watch for.
+     */
+    async watchWorkers(...workerNames) {
+        if (!this._registry) {
+            return;
+        }
+        for (const workerName of workerNames) {
+            logger.debug(`Worker '${this}': watching for worker '${workerName}'`);
+            await this._registry.watch(workerName, this._onWatchedWorkerReadyHandler);
+        }
+    }
+    /**
+     * Send a job request to a single worker (fire-and-forget).
+     *
+     * Waits for the worker to be ready before sending the request. Does not
+     * wait for the job to complete; use callbacks (`onJobResponse`,
+     * `onJobCompleted`) or `job()` for that.
+     *
+     * @param workerName Name of the worker to send the job to.
+     * @param options.params How to run the job. See `JobParams`.
+     * @returns The generated jobId.
+     */
+    async requestJob(workerName, options = {}) {
+        const jobParams = options.params ?? new JobParams();
+        const group = await this.createJobGroupAndRequestJob([workerName], {
+            params: new JobGroupParams({
+                name: jobParams.name,
+                payload: jobParams.payload,
+                timeout: jobParams.timeout,
+                label: jobParams.label,
+                cancellable: jobParams.cancellable,
+            }),
+        });
+        return group.jobId;
+    }
+    /**
+     * Create a single-worker job context.
+     *
+     * Waits for the worker to be ready, sends a job request, and waits for the
+     * response on exit. Supports `for await` inside the block to receive
+     * intermediate events (updates and streaming data) from the worker while
+     * waiting.
+     *
+     * On normal completion, the result is available via `response`. On worker
+     * error or timeout, throws `JobError`.
+     *
+     * @param workerName Name of the worker to send the job to.
+     * @param options.params How to run the job. See `JobParams`.
+     * @returns A `JobContext` (Python's `async with` → `await ctx.run(...)`).
+     *
+     * @example
+     * const t = this.job("worker", { params: new JobParams({ payload: data }) });
+     * await t.run(async (t) => {
+     *   for await (const event of t) {
+     *     if (event.type === JobEvent.UPDATE) console.log(event.data);
+     *   }
+     * });
+     * console.log(t.response);
+     */
+    job(workerName, options = {}) {
+        return new JobContext(this, workerName, { params: options.params ?? new JobParams() });
+    }
+    async requestJobGroup(...args) {
+        const [workerNames, options] = splitTrailingOptions(args, (v) => typeof v === "string");
+        checkWorkerNames(this, workerNames);
+        const groupParams = options.params ?? new JobGroupParams();
+        const group = await this.createJobGroupAndRequestJob([...workerNames], {
+            params: groupParams,
+        });
+        return group.jobId;
+    }
+    jobGroup(...args) {
+        const [workerNames, options] = splitTrailingOptions(args, (v) => typeof v === "string");
+        checkWorkerNames(this, workerNames);
+        const groupParams = options.params ?? new JobGroupParams();
+        return new JobGroupContext(this, workerNames, { params: groupParams });
+    }
+    /**
+     * Cancel a running job group.
+     *
+     * @param jobId The job identifier to cancel.
+     * @param options.reason Optional human-readable reason for cancellation.
+     */
+    async cancelJobGroup(jobId, options = {}) {
+        const reason = options.reason ?? null;
+        const group = this._jobGroups.get(jobId);
+        this._jobGroups.delete(jobId);
+        if (group) {
+            // On the timeout path this runs on the timeout task itself, which is
+            // already on its last statement. Cancelling it here would abandon the
+            // rest of this method, leaving the group's waiter blocked forever.
+            if (group.timeoutTask && group.timeoutTask !== currentTask()) {
+                await this.cancelTask(group.timeoutTask);
+            }
+            for (const workerName of group.workerNames) {
+                await this.sendBusMessage(new BusJobCancelMessage({ source: this.name, target: workerName, jobId, reason }));
+            }
+            group.fail(reason);
+        }
+    }
+    /**
+     * Honor an externally requested cancellation, if the group allows it.
+     *
+     * The door for cancellation asked for from outside the worker, by a client
+     * UI or an operator endpoint, which `JobGroupParams.cancellable` governs.
+     * Cancellation the worker decides on itself (shutdown, a timeout,
+     * `cancelOnError`) goes straight to `cancelJobGroup()` and is never
+     * refused.
+     *
+     * @param jobId The job identifier to cancel.
+     * @param options.reason Optional human-readable reason for cancellation.
+     * @returns Whether the group was cancelled. False means it is unknown or
+     *   was dispatched as non-cancellable.
+     */
+    async requestCancelJobGroup(jobId, options = {}) {
+        const group = this._jobGroups.get(jobId);
+        if (group === undefined || !group.cancellable) {
+            return false;
+        }
+        await this.cancelJobGroup(jobId, { reason: options.reason ?? null });
+        return true;
+    }
+    /**
+     * Request a progress update from a worker.
+     *
+     * @param jobId The job identifier.
+     * @param workerName The name of the worker to request an update from.
+     */
+    async requestJobUpdate(jobId, workerName) {
+        await this.sendBusMessage(new BusJobUpdateRequestMessage({ source: this.name, target: workerName, jobId }));
+    }
+    /**
+     * Wait for workers to be ready, create a job group, and send requests.
+     *
+     * Waits for all workers to be registered as ready, then creates the group
+     * and sends a job request to each worker. Does not wait for the group to
+     * complete; call `group.wait()` or use `jobGroup()` for that.
+     *
+     * @param workerNames Names of the workers to send the job to.
+     * @param options.params How to run the group. See `JobGroupParams`.
+     * @returns The created `JobGroup`.
+     * @throws JobGroupError If workers are not ready within the timeout.
+     */
+    async createJobGroupAndRequestJob(workerNames, options = {}) {
+        const groupParams = options.params ?? new JobGroupParams();
+        const allReady = await this._waitWorkersReady(workerNames);
+        try {
+            await waitFor(allReady, groupParams.timeout);
+        }
+        catch (e) {
+            if (e instanceof TimeoutError) {
+                throw new JobGroupError("workers not ready within timeout");
+            }
+            throw e;
+        }
+        const group = this._createJobGroup(workerNames, { params: groupParams });
+        for (const workerName of workerNames) {
+            await this._sendJobRequest(workerName, group.jobId, {
+                jobName: groupParams.name,
+                payload: groupParams.payload,
+            });
+        }
+        return group;
+    }
+    /**
+     * Send a job response back to the requester.
+     *
+     * After sending, the job is removed from the set of active jobs.
+     *
+     * @param jobId The identifier of the job being responded to.
+     * @param response Optional result data.
+     * @param options.status Completion status. Defaults to `JobStatus.COMPLETED`.
+     * @param options.urgent When true, the response is delivered with system
+     *   priority, preempting queued data messages.
+     * @throws Error If there is no active job with this `jobId`.
+     */
+    async sendJobResponse(jobId, response = null, options = {}) {
+        const status = options.status ?? JobStatus.COMPLETED;
+        const urgent = options.urgent ?? false;
+        const request = this._activeJobs.get(jobId);
+        if (request === undefined) {
+            throw new Error(`Worker '${this}': no active job '${jobId}' to respond to`);
+        }
+        const MsgClass = urgent ? BusJobResponseUrgentMessage : BusJobResponseMessage;
+        await this.sendBusMessage(new MsgClass({
+            source: this.name,
+            target: request.source,
+            jobId,
+            response,
+            status,
+        }));
+        this._activeJobs.delete(jobId);
+    }
+    /**
+     * Send a progress update to the requester.
+     *
+     * @param jobId The identifier of the job being updated.
+     * @param update Optional progress data.
+     * @param options.urgent When true, the update is delivered with system
+     *   priority, preempting queued data messages.
+     * @throws Error If there is no active job with this `jobId`.
+     */
+    async sendJobUpdate(jobId, update = null, options = {}) {
+        const urgent = options.urgent ?? false;
+        const request = this._activeJobs.get(jobId);
+        if (request === undefined) {
+            throw new Error(`Worker '${this}': no active job '${jobId}' to update`);
+        }
+        const MsgClass = urgent ? BusJobUpdateUrgentMessage : BusJobUpdateMessage;
+        await this.sendBusMessage(new MsgClass({
+            source: this.name,
+            target: request.source,
+            jobId,
+            update,
+        }));
+    }
+    /**
+     * Begin streaming job results back to the requester.
+     *
+     * @param jobId The identifier of the job being streamed.
+     * @param data Optional metadata about the stream.
+     * @throws Error If there is no active job with this `jobId`.
+     */
+    async sendJobStreamStart(jobId, data = null) {
+        const request = this._activeJobs.get(jobId);
+        if (request === undefined) {
+            throw new Error(`Worker '${this}': no active job '${jobId}' to stream`);
+        }
+        await this.sendBusMessage(new BusJobStreamStartMessage({
+            source: this.name,
+            target: request.source,
+            jobId,
+            data,
+        }));
+    }
+    /**
+     * Send a streaming chunk to the requester.
+     *
+     * @param jobId The identifier of the job being streamed.
+     * @param data The chunk payload.
+     * @throws Error If there is no active job with this `jobId`.
+     */
+    async sendJobStreamData(jobId, data = null) {
+        const request = this._activeJobs.get(jobId);
+        if (request === undefined) {
+            throw new Error(`Worker '${this}': no active job '${jobId}' to stream`);
+        }
+        await this.sendBusMessage(new BusJobStreamDataMessage({
+            source: this.name,
+            target: request.source,
+            jobId,
+            data,
+        }));
+    }
+    /**
+     * End the current stream and mark this worker's job as complete.
+     *
+     * After sending, the job is removed from the set of active jobs.
+     *
+     * @param jobId The identifier of the job being streamed.
+     * @param data Optional final metadata.
+     * @throws Error If there is no active job with this `jobId`.
+     */
+    async sendJobStreamEnd(jobId, data = null) {
+        const request = this._activeJobs.get(jobId);
+        if (request === undefined) {
+            throw new Error(`Worker '${this}': no active job '${jobId}' to stream`);
+        }
+        await this.sendBusMessage(new BusJobStreamEndMessage({
+            source: this.name,
+            target: request.source,
+            jobId,
+            data,
+        }));
+        this._activeJobs.delete(jobId);
+    }
+    /**
+     * Register this worker as ready in the shared registry.
+     *
+     * The registry notifies watchers (parent for children, runner for root
+     * workers).
+     */
+    async _registerReady() {
+        if (this._registry) {
+            // Send the bus message before registering. Registration fires watchers
+            // synchronously, which may send additional messages (e.g.
+            // ActivateWorker). Sending the ready message first preserves correct
+            // chronological order for observers.
+            await this.sendBusMessage(new BusWorkerReadyMessage({
+                source: this.name,
+                runner: this._registry.runnerName,
+                parent: this._parent,
+                active: this._active,
+                bridged: this.bridged,
+                startedAt: this._startedAt,
+            }));
+            await this._registry.register(new WorkerReadyData({
+                workerName: this.name,
+                runner: this._registry.runnerName,
+            }));
+        }
+    }
+    /** Activate the worker, call onActivated, and fire event handlers. */
+    async _maybeActivate() {
+        if (this._startedAt !== null && this._pendingActivation) {
+            logger.debug(`Worker '${this}': activated`);
+            this._active = true;
+            this._pendingActivation = false;
+            await this.onActivated(this._activationArgs);
+            await this._callEventHandler("on_activated", this._activationArgs);
+        }
+    }
+    /** Register watches for all `workerReady` decorated handlers. */
+    async _watchDecoratedWorkers() {
+        await this.watchWorkers(...this._workerReadyHandlers.keys());
+    }
+    /**
+     * Called when a watched worker is ready.
+     *
+     * Dispatches to the `workerReady` handler if one exists for this worker,
+     * otherwise proxies to `onWorkerReady`.
+     */
+    async _onWatchedWorkerReady(data) {
+        logger.debug(`Worker '${this}': worker '${data.workerName}' ready`);
+        const handler = this._workerReadyHandlers.get(data.workerName);
+        if (handler) {
+            await handler(data);
+        }
+        await this.onWorkerReady(data);
+        await this._callEventHandler("on_worker_ready", data);
+    }
+    /** Handle an error reported by a child or remote worker. */
+    async _handleWorkerError(message) {
+        const childNames = new Set(this._children.map((child) => child.name));
+        if (childNames.has(message.source)) {
+            const errorInfo = new WorkerErrorData({ workerName: message.source, error: message.error });
+            await this.onWorkerFailed(errorInfo);
+            await this._callEventHandler("on_worker_failed", errorInfo);
+        }
+    }
+    /**
+     * Handle an activation message.
+     *
+     * Stores the activation arguments and marks the worker as pending
+     * activation, then delegates to `_maybeActivate()`.
+     *
+     * @param message The `BusActivateWorkerMessage` requesting activation.
+     */
+    async _handleWorkerActivate(message) {
+        this._activationArgs = message.args;
+        this._pendingActivation = true;
+        await this._maybeActivate();
+    }
+    /**
+     * Deactivate this worker.
+     *
+     * @param message The `BusDeactivateWorkerMessage` requesting deactivation.
+     */
+    async _handleWorkerDeactivate(_message) {
+        logger.debug(`Worker '${this}': deactivated`);
+        this._active = false;
+        this._activationArgs = null;
+        await this.onDeactivated();
+        await this._callEventHandler("on_deactivated");
+    }
+    /**
+     * Propagate end to children, wait for them, then stop this worker.
+     *
+     * Subclasses with their own runtime (e.g. `PipelineWorker`) call
+     * `_propagateEndToChildren()` directly and drive their own shutdown so
+     * `_finishedEvent` fires at the right moment.
+     *
+     * @param message The `BusEndWorkerMessage` requesting a graceful end.
+     */
+    async _handleWorkerEnd(message) {
+        logger.debug(`Worker '${this}': received end`);
+        await this._propagateEndToChildren(message);
+        await this.stop();
+    }
+    /**
+     * Propagate cancel to children, then stop this worker.
+     *
+     * Subclasses with their own runtime (e.g. `PipelineWorker`) call
+     * `_propagateCancelToChildren()` directly and drive their own shutdown so
+     * `_finishedEvent` fires at the right moment.
+     *
+     * @param message The `BusCancelWorkerMessage` requesting cancellation.
+     */
+    async _handleWorkerCancel(message) {
+        logger.debug(`Worker '${this}': received cancel`);
+        await this._propagateCancelToChildren(message);
+        await this.stop();
+    }
+    /** Forward a `BusEndWorkerMessage` to each child and wait for them. */
+    async _propagateEndToChildren(message) {
+        for (const child of this._children) {
+            await this.sendBusMessage(new BusEndWorkerMessage({ source: this.name, target: child.name, reason: message.reason }));
+        }
+        await gather(...this._children.map((child) => () => child.wait()));
+    }
+    /** Forward a `BusCancelWorkerMessage` to each child. */
+    async _propagateCancelToChildren(message) {
+        for (const child of this._children) {
+            await this.sendBusMessage(new BusCancelWorkerMessage({
+                source: this.name,
+                target: child.name,
+                reason: message.reason,
+            }));
+        }
+    }
+    /**
+     * Handle an incoming job request.
+     *
+     * Dispatches to `job()` handlers if any match, otherwise falls back to
+     * onJobRequest. The handler always runs in its own task so the bus message
+     * loop is never blocked. When the matched handler is marked
+     * `sequential: true`, requests with the same job name are queued and run
+     * one at a time in FIFO order.
+     */
+    async _handleJobRequest(message) {
+        this._activeJobs.set(message.jobId, message);
+        let handler = message.jobName
+            ? this._jobHandlers.get(message.jobName)
+            : undefined;
+        if (handler === undefined) {
+            handler = (m) => this.onJobRequest(m);
+        }
+        let lock = null;
+        if (message.jobName && handler.jobSequential) {
+            lock = this._jobLocks.get(message.jobName) ?? null;
+            if (lock === null) {
+                lock = new Lock();
+                this._jobLocks.set(message.jobName, lock);
+            }
+        }
+        const jobHandler = handler;
+        const task = this.createTask(() => this._runJobHandler(message.jobId, jobHandler, message, lock), `${this.name}::job_${message.jobName || "default"}`);
+        this._jobHandlerTasks.set(message.jobId, task);
+        await this._callEventHandler("on_job_request", message);
+    }
+    async _runJobHandler(jobId, handler, message, lock = null) {
+        try {
+            if (lock !== null) {
+                await lock.run(async () => {
+                    await handler(message);
+                });
+            }
+            else {
+                await handler(message);
+            }
+        }
+        catch (e) {
+            if (!(e instanceof CancelledError))
+                throw e;
+        }
+        finally {
+            this._jobHandlerTasks.delete(jobId);
+        }
+    }
+    /** Handle a job response and track group completion. */
+    async _handleJobResponse(message) {
+        this._markWorkerTerminated(message.jobId, message.source);
+        await this.onJobResponse(message);
+        await this._callEventHandler("on_job_response", message);
+        // Auto-cancel the group on error/failed if cancelOnError is set
+        if (message.status === JobStatus.ERROR || message.status === JobStatus.FAILED) {
+            const group = this._jobGroups.get(message.jobId);
+            if (group?.cancelOnError) {
+                group.responses[message.source] = message.response ?? {};
+                await this.onJobError(message);
+                await this._callEventHandler("on_job_error", message);
+                await this.cancelJobGroup(message.jobId, {
+                    reason: `worker '${message.source}' errored`,
+                });
+                return;
+            }
+        }
+        await this._trackJobGroupResponse(message.jobId, message.source, message.response);
+    }
+    /**
+     * Record that a worker of a group has reached a terminal state.
+     *
+     * A worker terminates either by responding or by ending its stream.
+     * `cancelJobGroup` reads this to tell apart the workers a cancellation
+     * actually cut short from those that had already finished on their own.
+     */
+    _markWorkerTerminated(jobId, workerName) {
+        const group = this._jobGroups.get(jobId);
+        if (group) {
+            group.terminated.add(workerName);
+        }
+    }
+    /** Handle a job progress update. */
+    async _handleJobUpdate(message) {
+        await this.onJobUpdate(message);
+        await this._callEventHandler("on_job_update", message);
+        this._pushJobGroupEvent(message.jobId, new JobGroupEvent({
+            type: JobGroupEvent.UPDATE,
+            workerName: message.source,
+            data: message.update,
+        }));
+    }
+    /** Handle a job update request from the requester. */
+    async _handleJobUpdateRequest(message) {
+        if (this._activeJobs.has(message.jobId)) {
+            await this.onJobUpdateRequested(message);
+            await this._callEventHandler("on_job_update_requested", message);
+        }
+    }
+    /**
+     * Handle a job cancellation.
+     *
+     * Cancels the running handler task (if any), calls the `onJobCancelled`
+     * hook for cleanup, then automatically sends a cancelled response back to
+     * the requester. The requester receives `onJobResponse` with
+     * `status: "cancelled"`, same path as completed or failed jobs.
+     */
+    async _handleJobCancel(message) {
+        if (this._activeJobs.has(message.jobId)) {
+            const handlerTask = this._jobHandlerTasks.get(message.jobId);
+            if (handlerTask) {
+                await this.cancelTask(handlerTask);
+            }
+            await this.onJobCancelled(message);
+            await this._callEventHandler("on_job_cancelled", message);
+            await this.sendJobResponse(message.jobId, null, { status: JobStatus.CANCELLED });
+        }
+    }
+    /** Handle the start of a streaming job response. */
+    async _handleJobStreamStart(message) {
+        await this.onJobStreamStart(message);
+        await this._callEventHandler("on_job_stream_start", message);
+        this._pushJobGroupEvent(message.jobId, new JobGroupEvent({
+            type: JobGroupEvent.STREAM_START,
+            workerName: message.source,
+            data: message.data,
+        }));
+    }
+    /** Handle a streaming job data chunk. */
+    async _handleJobStreamData(message) {
+        await this.onJobStreamData(message);
+        await this._callEventHandler("on_job_stream_data", message);
+        this._pushJobGroupEvent(message.jobId, new JobGroupEvent({
+            type: JobGroupEvent.STREAM_DATA,
+            workerName: message.source,
+            data: message.data,
+        }));
+    }
+    /** Handle the end of a streaming job response. */
+    async _handleJobStreamEnd(message) {
+        this._markWorkerTerminated(message.jobId, message.source);
+        await this.onJobStreamEnd(message);
+        await this._callEventHandler("on_job_stream_end", message);
+        this._pushJobGroupEvent(message.jobId, new JobGroupEvent({
+            type: JobGroupEvent.STREAM_END,
+            workerName: message.source,
+            data: message.data,
+        }));
+        await this._trackJobGroupResponse(message.jobId, message.source, message.data);
+    }
+    _createJobGroup(workerNames, options) {
+        const { params } = options;
+        const jobId = crypto.randomUUID();
+        const group = new JobGroup({
+            jobId,
+            workerNames: [...workerNames],
+            cancelOnError: params.cancelOnError,
+            label: params.label,
+            cancellable: params.cancellable,
+        });
+        this._jobGroups.set(jobId, group);
+        const timeout = params.timeout;
+        if (timeout !== null) {
+            group.timeoutTask = this.createTask(() => this._taskTimeout(jobId, timeout), `task_timeout_${jobId.slice(0, 8)}`);
+        }
+        return group;
+    }
+    /**
+     * Return a coroutine function that resolves when all named workers are ready.
+     *
+     * The watches are registered before this returns; callers race the
+     * returned function against a timeout (`waitFor(allReady, timeout)`) or a
+     * group done signal. Upstream returns an `asyncio.Future`; a function is
+     * returned here because awaiting an async function that returns a Task
+     * would adopt (wait for) it.
+     *
+     * @throws Error If the registry is not available.
+     */
+    async _waitWorkersReady(workerNames) {
+        if (!this._registry) {
+            throw new Error(`Worker '${this}': registry not available`);
+        }
+        const readyEvents = new Map();
+        for (const name of workerNames) {
+            const event = new Event();
+            readyEvents.set(name, event);
+            const onReady = async (_data) => {
+                event.set();
+            };
+            await this._registry.watch(name, onReady);
+        }
+        return async () => {
+            await gather(...[...readyEvents.values()].map((ev) => () => ev.wait()));
+        };
+    }
+    async _sendJobRequest(workerName, jobId, options = {}) {
+        await this.sendBusMessage(new BusJobRequestMessage({
+            source: this.name,
+            target: workerName,
+            jobId,
+            jobName: options.jobName ?? null,
+            payload: options.payload ?? null,
+        }));
+    }
+    async _taskTimeout(jobId, timeout) {
+        try {
+            await sleep(timeout);
+        }
+        catch (e) {
+            if (e instanceof CancelledError)
+                return;
+            throw e;
+        }
+        await this.cancelJobGroup(jobId, { reason: "timeout" });
+    }
+    _pushJobGroupEvent(jobId, event) {
+        const group = this._jobGroups.get(jobId);
+        if (group?.eventQueue) {
+            group.eventQueue.putNowait(event);
+        }
+    }
+    /** Record a worker's response and fire completion when all have responded. */
+    async _trackJobGroupResponse(jobId, source, response) {
+        const group = this._jobGroups.get(jobId);
+        if (group) {
+            group.responses[source] = response ?? {};
+            if (group.workerNames.every((name) => Object.hasOwn(group.responses, name))) {
+                if (group.timeoutTask) {
+                    await this.cancelTask(group.timeoutTask);
+                }
+                this._jobGroups.delete(jobId);
+                const result = new JobGroupResponse({ jobId, responses: group.responses });
+                await this.onJobCompleted(result);
+                await this._callEventHandler("on_job_completed", result);
+                group.complete();
+            }
+        }
+    }
+    /** Warn about tasks left running on the task manager this worker owns. */
+    _printDanglingTasks() {
+        if (this._checkDanglingTasks && this._ownsTaskManager) {
+            const tasks = this.taskManager.currentTasks().map((t) => t.getName());
+            if (tasks.length > 0) {
+                logger.warning(`${this} dangling tasks detected: [${tasks.map((t) => `'${t}'`).join(", ")}]`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=base_worker.js.map