@pipedog/core 0.0.0 → 0.1.0

package/dist/workers/base_worker.d.ts

@@ -0,0 +1,772 @@
+/**
+ * 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 { Event, Lock, type Task, type TaskFn } from "@pipedog/asyncio";
+import type { WorkerBus } from "../bus/bus.ts";
+import { BusActivateWorkerMessage, BusCancelWorkerMessage, BusDeactivateWorkerMessage, BusEndWorkerMessage, BusJobCancelMessage, BusJobRequestMessage, BusJobResponseMessage, BusJobResponseUrgentMessage, BusJobStreamDataMessage, BusJobStreamEndMessage, BusJobStreamStartMessage, BusJobUpdateMessage, BusJobUpdateRequestMessage, BusJobUpdateUrgentMessage, type BusMessage, BusWorkerErrorMessage, BusWorkerLocalErrorMessage } from "../bus/messages.ts";
+import { JobContext, JobGroup, JobGroupContext, JobGroupEvent, JobGroupParams, JobGroupResponse, JobParams, JobStatus } from "../pipeline/job_context.ts";
+import type { WorkerRegistry } from "../registry/registry.ts";
+import { WorkerErrorData, WorkerReadyData } from "../registry/types.ts";
+import type { BaseTaskManager } from "../utils/asyncio/task_manager.ts";
+import { BaseObject, type BaseObjectOptions } from "../utils/base_object.ts";
+import type { WorkerRunner } from "./runner.ts";
+type Dict = Record<string, unknown>;
+type JobHandlerFn = (message: BusJobRequestMessage) => Promise<unknown> | unknown;
+export interface WorkerParamsOptions {
+    /** Task manager for handling asyncio tasks. */
+    taskManager: BaseTaskManager;
+}
+/**
+ * Configuration parameters for worker execution.
+ *
+ * - `taskManager`: Task manager for handling asyncio tasks.
+ */
+export declare class WorkerParams {
+    taskManager: BaseTaskManager;
+    constructor(options: WorkerParamsOptions);
+}
+export interface WorkerActivationArgsOptions {
+    /** Optional structured data passed during activation. */
+    metadata?: Dict | null;
+}
+/**
+ * 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 declare class WorkerActivationArgs {
+    metadata: Dict | null;
+    constructor(options?: WorkerActivationArgsOptions);
+    /** Create from a dict, ignoring unknown keys. */
+    static fromDict<T extends WorkerActivationArgs>(this: new (options?: Dict) => T, data: Dict): T;
+    /** Convert to a dict, excluding null values. */
+    toDict(): Dict;
+}
+export interface BaseWorkerOptions extends BaseObjectOptions {
+    /**
+     * Unique name for this worker. If null, an auto-generated name is used
+     * (useful for instances that don't participate in inter-worker
+     * communication).
+     */
+    name?: string | null;
+    /**
+     * Whether the worker starts out accepting bus messages (see `active`).
+     * Starting one inactive is for multi-worker setups where workers take
+     * turns: it stays out of the way, doing nothing, until another worker or
+     * the application activates it. Defaults to true.
+     */
+    active?: boolean;
+    /**
+     * Whether to warn about tasks left running when the worker finishes. Only
+     * applies when the worker owns its task manager; a worker sharing the
+     * runner's task manager leaves the report to the runner. Defaults to true.
+     */
+    checkDanglingTasks?: boolean;
+    /** Optional task manager for handling asyncio tasks. */
+    taskManager?: BaseTaskManager | null;
+}
+export interface AttachOptions {
+    /** The shared worker registry. */
+    registry: WorkerRegistry;
+    /** The shared worker bus. */
+    bus: WorkerBus;
+    /** The runner hosting the worker, reachable afterwards as `workerRunner`. */
+    workerRunner: WorkerRunner;
+}
+export interface AddWorkersOptions {
+    /**
+     * When true (the default), watch each newly added child so
+     * `onWorkerReady` fires once it registers. Workers that were skipped
+     * (already parented elsewhere) are not watched.
+     */
+    watch?: boolean;
+}
+export interface ActivateWorkerOptions {
+    /** Optional `WorkerActivationArgs` forwarded to the target worker's `onActivated`. */
+    args?: WorkerActivationArgs | null;
+    /** Whether to deactivate this worker before activating the target. */
+    deactivateSelf?: boolean;
+}
+export interface JobOptions {
+    /** How to run the job. See `JobParams`. */
+    params?: JobParams | null;
+}
+export interface JobGroupOptions {
+    /** How to run the group. See `JobGroupParams`. */
+    params?: JobGroupParams | null;
+}
+export interface SendJobResponseOptions {
+    /** Completion status. Defaults to `JobStatus.COMPLETED`. */
+    status?: JobStatus;
+    /** When true, the response is delivered with system priority, preempting queued data messages. */
+    urgent?: boolean;
+}
+export interface SendJobUpdateOptions {
+    /** When true, the update is delivered with system priority, preempting queued data messages. */
+    urgent?: boolean;
+}
+declare const BaseWorker_base: typeof BaseObject & import("../utils/mixin.ts").Ctor<import("../bus/subscriber.ts").BusSubscriberMethods>;
+/**
+ * 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 declare class BaseWorker extends BaseWorker_base {
+    protected _checkDanglingTasks: boolean;
+    protected _ownsTaskManager: boolean;
+    protected _bus: WorkerBus | null;
+    protected _registry: WorkerRegistry | null;
+    protected _workerRunner: WorkerRunner | null;
+    protected _active: boolean;
+    protected _pendingActivation: boolean;
+    protected _activationArgs: Dict | null;
+    protected _parent: string | null;
+    protected _children: BaseWorker[];
+    protected _startedAt: number | null;
+    protected _finishedEvent: Event;
+    protected _activeJobs: Map<string, BusJobRequestMessage>;
+    protected _jobHandlerTasks: Map<string, Task<unknown>>;
+    protected _jobGroups: Map<string, JobGroup>;
+    protected _jobHandlers: Map<string, JobHandlerFn>;
+    protected _jobLocks: Map<string, Lock>;
+    protected _workerReadyHandlers: Map<string, (data: WorkerReadyData) => unknown>;
+    protected readonly _onWatchedWorkerReadyHandler: (data: WorkerReadyData) => Promise<void>;
+    /** Initialize the BaseWorker. */
+    constructor(options?: BaseWorkerOptions);
+    /**
+     * The bus this worker is attached to.
+     *
+     * @throws Error If accessed before `attach()` has been called.
+     */
+    get bus(): WorkerBus;
+    /**
+     * 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(): boolean;
+    /** The arguments from the most recent activation, or null if inactive. */
+    get activationArgs(): Dict | null;
+    /** The name of the parent worker, or null if this is a root worker. */
+    get parent(): string | null;
+    /**
+     * The shared worker registry this worker is attached to.
+     *
+     * @throws Error If accessed before `attach()` has been called.
+     */
+    get registry(): WorkerRegistry;
+    /**
+     * 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(): WorkerRunner;
+    /** Unix timestamp (seconds) when this worker became ready, or null if not yet started. */
+    get startedAt(): number | null;
+    /**
+     * 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(): boolean;
+    /** The list of child workers added via `addWorkers()`. */
+    get children(): BaseWorker[];
+    /** Active job requests this worker is currently working on, keyed by jobId. */
+    get activeJobs(): Map<string, BusJobRequestMessage>;
+    /** Active job groups launched by this worker, keyed by jobId. */
+    get jobGroups(): Map<string, JobGroup>;
+    /**
+     * 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.
+     */
+    attach(options: AttachOptions): Promise<void>;
+    /**
+     * Clean up the worker and release resources.
+     *
+     * Cancels running jobs, unsubscribes from the bus, and signals that the
+     * worker has stopped.
+     */
+    cleanup(): Promise<void>;
+    /**
+     * 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.
+     */
+    run(params: WorkerParams): Promise<void>;
+    /** Mark the worker as started, register, and activate if requested. */
+    start(): Promise<void>;
+    /**
+     * 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.
+     */
+    stop(): Promise<void>;
+    /**
+     * Request a graceful end of the session.
+     *
+     * @param options.reason Optional human-readable reason for ending.
+     */
+    end(options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /**
+     * Request an immediate cancellation of all workers.
+     *
+     * @param options.reason Optional human-readable reason. Propagated through
+     *   the runner to every root worker's `BusCancelWorkerMessage`.
+     */
+    cancel(options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /** Wait for this worker to finish. */
+    wait(): Promise<void>;
+    /**
+     * 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.
+     */
+    onActivated(_args: Dict | null): Promise<void>;
+    /**
+     * Called when this worker is deactivated.
+     *
+     * Override in subclasses to react to deactivation. Always call
+     * `super.onDeactivated()`.
+     */
+    onDeactivated(): Promise<void>;
+    /**
+     * 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.
+     */
+    onWorkerReady(_data: WorkerReadyData): Promise<void>;
+    /**
+     * Called when a child worker reports an error.
+     *
+     * @param data Information about the error.
+     */
+    onWorkerFailed(_data: WorkerErrorData): Promise<void>;
+    /**
+     * 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: BusMessage): boolean;
+    /**
+     * 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.
+     */
+    onBusMessage(message: BusMessage): Promise<void>;
+    /**
+     * Called when this worker receives a job request.
+     *
+     * Override to perform work. Use `sendJobUpdate()` to report progress and
+     * `sendJobResponse()` to return results.
+     */
+    onJobRequest(_message: BusJobRequestMessage): Promise<void>;
+    /**
+     * Called when a worker sends a response.
+     *
+     * Override to process individual results as they arrive.
+     */
+    onJobResponse(_message: BusJobResponseMessage | BusJobResponseUrgentMessage): Promise<void>;
+    /** Called when a worker sends a progress update. */
+    onJobUpdate(_message: BusJobUpdateMessage | BusJobUpdateUrgentMessage): Promise<void>;
+    /**
+     * Called when the requester asks for a progress update.
+     *
+     * Override to send back a progress update via `sendJobUpdate()`.
+     */
+    onJobUpdateRequested(_message: BusJobUpdateRequestMessage): Promise<void>;
+    /** Called when all workers in a job group have responded. */
+    onJobCompleted(_result: JobGroupResponse): Promise<void>;
+    /**
+     * 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`.
+     */
+    onJobError(_message: BusJobResponseMessage | BusJobResponseUrgentMessage): Promise<void>;
+    /** Called when a worker begins streaming. */
+    onJobStreamStart(_message: BusJobStreamStartMessage): Promise<void>;
+    /** Called for each streaming chunk from a worker. */
+    onJobStreamData(_message: BusJobStreamDataMessage): Promise<void>;
+    /** Called when a worker finishes streaming. */
+    onJobStreamEnd(_message: BusJobStreamEndMessage): Promise<void>;
+    /**
+     * Called when this worker's job is cancelled by the requester.
+     *
+     * Override to clean up resources or stop in-progress work.
+     */
+    onJobCancelled(_message: BusJobCancelMessage): Promise<void>;
+    /**
+     * Send a message on the bus.
+     *
+     * @param message The `BusMessage` to send.
+     */
+    sendBusMessage(message: BusMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    sendBusErrorMessage(error: string): Promise<void>;
+    /**
+     * Register one or more child workers under this parent.
+     *
+     * Each child's lifecycle (end, cancel) is automatically managed by this
+     * parent worker. By default, the children are also watched so the parent
+     * receives `onWorkerReady` when each one starts; pass `{ watch: false }`
+     * as the last argument to opt out (you can still call `watchWorkers()`
+     * later).
+     *
+     * @example
+     * await this.addWorkers(researcher, writer);
+     * await this.addWorkers(researcher, writer, { watch: false });
+     */
+    addWorkers(...args: [...workers: BaseWorker[], options: AddWorkersOptions]): Promise<void>;
+    addWorkers(...workers: BaseWorker[]): Promise<void>;
+    /**
+     * 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.
+     */
+    activateWorker(workerName: string, options?: ActivateWorkerOptions): Promise<void>;
+    /**
+     * Deactivate a worker by name.
+     *
+     * The target worker's `onDeactivated` hook will be called.
+     *
+     * @param workerName The name of the worker to deactivate.
+     */
+    deactivateWorker(workerName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    watchWorkers(...workerNames: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    requestJob(workerName: string, options?: JobOptions): Promise<string>;
+    /**
+     * 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: string, options?: JobOptions): JobContext;
+    /**
+     * Send a job request to multiple workers (fire-and-forget).
+     *
+     * Waits for all workers to be ready before sending requests. Does not
+     * wait for the job group to complete; use callbacks (`onJobResponse`,
+     * `onJobCompleted`) or `jobGroup()` for that.
+     *
+     * @param args Names of the workers to send the job to, optionally followed
+     *   by `{ params }` (see `JobGroupParams`).
+     * @returns The generated jobId shared by all workers in the group.
+     * @throws TypeError If a worker name is not a string.
+     */
+    requestJobGroup(...args: [...workerNames: string[], options: JobGroupOptions]): Promise<string>;
+    requestJobGroup(...workerNames: string[]): Promise<string>;
+    /**
+     * Create a job group context.
+     *
+     * Waits for workers to be ready, sends job requests, and waits for all
+     * responses on exit. Supports `for await` inside the block to receive
+     * intermediate events (updates and streaming data) from workers while
+     * waiting.
+     *
+     * On normal completion, results are available via `responses`. On worker
+     * error (with `cancelOnError: true`) or timeout, throws `JobGroupError`.
+     *
+     * @param args Names of the workers to send the job to, optionally followed
+     *   by `{ params }` (see `JobGroupParams`).
+     * @returns A `JobGroupContext` (Python's `async with` → `await ctx.run(...)`).
+     * @throws TypeError If a worker name is not a string.
+     *
+     * @example
+     * const tg = this.jobGroup("w1", "w2", { params: new JobGroupParams({ payload: data }) });
+     * await tg.run(async (tg) => {
+     *   for await (const event of tg) {
+     *     if (event.type === JobGroupEvent.UPDATE) console.log(`${event.workerName}: ${event.data}`);
+     *   }
+     * });
+     * for (const [name, result] of Object.entries(tg.responses)) console.log(name, result);
+     */
+    jobGroup(...args: [...workerNames: string[], options: JobGroupOptions]): JobGroupContext;
+    jobGroup(...workerNames: string[]): JobGroupContext;
+    /**
+     * Cancel a running job group.
+     *
+     * @param jobId The job identifier to cancel.
+     * @param options.reason Optional human-readable reason for cancellation.
+     */
+    cancelJobGroup(jobId: string, options?: {
+        reason?: string | null;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    requestCancelJobGroup(jobId: string, options?: {
+        reason?: string | null;
+    }): Promise<boolean>;
+    /**
+     * Request a progress update from a worker.
+     *
+     * @param jobId The job identifier.
+     * @param workerName The name of the worker to request an update from.
+     */
+    requestJobUpdate(jobId: string, workerName: string): Promise<void>;
+    /**
+     * 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.
+     */
+    createJobGroupAndRequestJob(workerNames: string[], options?: JobGroupOptions): Promise<JobGroup>;
+    /**
+     * 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`.
+     */
+    sendJobResponse(jobId: string, response?: Dict | null, options?: SendJobResponseOptions): Promise<void>;
+    /**
+     * 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`.
+     */
+    sendJobUpdate(jobId: string, update?: Dict | null, options?: SendJobUpdateOptions): Promise<void>;
+    /**
+     * 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`.
+     */
+    sendJobStreamStart(jobId: string, data?: Dict | null): Promise<void>;
+    /**
+     * 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`.
+     */
+    sendJobStreamData(jobId: string, data?: Dict | null): Promise<void>;
+    /**
+     * 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`.
+     */
+    sendJobStreamEnd(jobId: string, data?: Dict | null): Promise<void>;
+    /**
+     * Register this worker as ready in the shared registry.
+     *
+     * The registry notifies watchers (parent for children, runner for root
+     * workers).
+     */
+    protected _registerReady(): Promise<void>;
+    /** Activate the worker, call onActivated, and fire event handlers. */
+    protected _maybeActivate(): Promise<void>;
+    /** Register watches for all `workerReady` decorated handlers. */
+    protected _watchDecoratedWorkers(): Promise<void>;
+    /**
+     * Called when a watched worker is ready.
+     *
+     * Dispatches to the `workerReady` handler if one exists for this worker,
+     * otherwise proxies to `onWorkerReady`.
+     */
+    protected _onWatchedWorkerReady(data: WorkerReadyData): Promise<void>;
+    /** Handle an error reported by a child or remote worker. */
+    protected _handleWorkerError(message: BusWorkerErrorMessage | BusWorkerLocalErrorMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _handleWorkerActivate(message: BusActivateWorkerMessage): Promise<void>;
+    /**
+     * Deactivate this worker.
+     *
+     * @param message The `BusDeactivateWorkerMessage` requesting deactivation.
+     */
+    protected _handleWorkerDeactivate(_message: BusDeactivateWorkerMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _handleWorkerEnd(message: BusEndWorkerMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _handleWorkerCancel(message: BusCancelWorkerMessage): Promise<void>;
+    /** Forward a `BusEndWorkerMessage` to each child and wait for them. */
+    protected _propagateEndToChildren(message: BusEndWorkerMessage): Promise<void>;
+    /** Forward a `BusCancelWorkerMessage` to each child. */
+    protected _propagateCancelToChildren(message: BusCancelWorkerMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _handleJobRequest(message: BusJobRequestMessage): Promise<void>;
+    protected _runJobHandler(jobId: string, handler: JobHandlerFn, message: BusJobRequestMessage, lock?: Lock | null): Promise<void>;
+    /** Handle a job response and track group completion. */
+    protected _handleJobResponse(message: BusJobResponseMessage | BusJobResponseUrgentMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _markWorkerTerminated(jobId: string, workerName: string): void;
+    /** Handle a job progress update. */
+    protected _handleJobUpdate(message: BusJobUpdateMessage | BusJobUpdateUrgentMessage): Promise<void>;
+    /** Handle a job update request from the requester. */
+    protected _handleJobUpdateRequest(message: BusJobUpdateRequestMessage): Promise<void>;
+    /**
+     * 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.
+     */
+    protected _handleJobCancel(message: BusJobCancelMessage): Promise<void>;
+    /** Handle the start of a streaming job response. */
+    protected _handleJobStreamStart(message: BusJobStreamStartMessage): Promise<void>;
+    /** Handle a streaming job data chunk. */
+    protected _handleJobStreamData(message: BusJobStreamDataMessage): Promise<void>;
+    /** Handle the end of a streaming job response. */
+    protected _handleJobStreamEnd(message: BusJobStreamEndMessage): Promise<void>;
+    protected _createJobGroup(workerNames: string[], options: {
+        params: JobGroupParams;
+    }): JobGroup;
+    /**
+     * 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.
+     */
+    protected _waitWorkersReady(workerNames: string[]): Promise<TaskFn<void>>;
+    protected _sendJobRequest(workerName: string, jobId: string, options?: {
+        jobName?: string | null;
+        payload?: Dict | null;
+    }): Promise<void>;
+    protected _taskTimeout(jobId: string, timeout: number): Promise<void>;
+    protected _pushJobGroupEvent(jobId: string, event: JobGroupEvent): void;
+    /** Record a worker's response and fire completion when all have responded. */
+    protected _trackJobGroupResponse(jobId: string, source: string, response: Dict | null): Promise<void>;
+    /** Warn about tasks left running on the task manager this worker owns. */
+    protected _printDanglingTasks(): void;
+}
+export {};
+//# sourceMappingURL=base_worker.d.ts.map