@dudousxd/nestjs-durable-core 0.41.0 → 0.43.0

package/dist/index.d.cts

@@ -837,6 +837,58 @@ interface Transport {
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
 }
+/** How a worker decides its concurrency, carried in {@link WorkerStatus} so a dashboard can tell a
+ *  fixed knob from a self-regulating one (and, for the latter, where the controller currently sits). */
+interface WorkerConcurrencyStatus {
+    /** `fixed` = the configured `concurrency` number, never moves. `adaptive` = the controller tunes it. */
+    mode: 'fixed' | 'adaptive';
+    /** The concurrency ceiling in effect right now (fixed: the configured value; adaptive: the live limit). */
+    limit: number;
+    /** Adaptive only — the floor the controller won't go below. */
+    min?: number;
+    /** Adaptive only — the ceiling the controller won't exceed. */
+    max?: number;
+}
+/** The adaptive controller's most recent limit change — the "why did it move" a dashboard shows so an
+ *  auto-tuner isn't a black box. Absent until the controller first adjusts (or for a fixed worker). */
+interface WorkerAdjust {
+    /** Epoch ms of the adjustment. */
+    at: number;
+    /** Limit before this change. */
+    from: number;
+    /** Limit after this change. */
+    to: number;
+    /** Why it moved: `ram_ceiling` (hard brake), `backpressure` (errors/stall), `grow` (had headroom),
+     *  `shrink` (latency gradient showed queuing), `cpu_ceiling`. */
+    reason: 'ram_ceiling' | 'cpu_ceiling' | 'backpressure' | 'grow' | 'shrink';
+}
+/** A live snapshot of a worker's execution state, carried in the worker-liveness heartbeat (so it
+ *  rides the existing TTL'd key — no extra round-trip) and surfaced per worker in the dashboard. Every
+ *  field beyond {@link concurrency}/{@link inFlight} is best-effort: a field a runtime can't measure is
+ *  simply omitted. The shape is shared by the TS and Python SDKs so a mixed-language group reports
+ *  uniformly. */
+interface WorkerStatus {
+    /** Which SDK is running this worker — `node` (TS) or `python`. */
+    runtime?: 'node' | 'python';
+    /** The worker's concurrency knob and its live ceiling. */
+    concurrency: WorkerConcurrencyStatus;
+    /** Tasks executing right now (0..limit). With `limit`, this is the saturation a dashboard charts. */
+    inFlight: number;
+    /** Resident set size in bytes, if the runtime can read it. */
+    rssBytes?: number;
+    /** The process memory ceiling in bytes (cgroup `memory.max`, else host total), if known. */
+    rssLimitBytes?: number;
+    /** RSS as a percent of {@link rssLimitBytes} (0..100) — what the adaptive RAM brake watches. */
+    rssPct?: number;
+    /** Process CPU utilisation percent over the last control tick (0..100×cores), if measured. */
+    cpuPct?: number;
+    /** Completed tasks per minute over the recent window — the controller's throughput signal. */
+    throughputPerMin?: number;
+    /** p95 of recent task durations in ms — the latency a dashboard charts against the limit. */
+    p95Ms?: number;
+    /** The adaptive controller's last limit change (absent for a fixed worker or before the first move). */
+    lastAdjust?: WorkerAdjust;
+}
 /** One worker's liveness record — a TTL'd heartbeat a worker refreshes while it's consuming. Its
  *  ABSENCE (the key expired) is the signal: a worker that died or stalled stops refreshing. */
 interface WorkerHeartbeat {
@@ -846,6 +898,9 @@ interface WorkerHeartbeat {
     instanceId: string;
     /** Epoch ms of the worker's most recent heartbeat. */
     lastBeatAt: number;
+    /** The worker's live execution snapshot, when its heartbeat carries one (newer SDKs stamp a JSON
+     *  value; an older SDK's bare-timestamp heartbeat leaves this undefined). */
+    status?: WorkerStatus;
 }
 /** Per-group worker-health snapshot: how much work is queued vs. how many workers are alive to do it.
  *  The actionable alert state is `depth > 0 && liveWorkers.length === 0` — work piling up with no
@@ -1581,6 +1636,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
@@ -2496,4 +2574,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };

package/dist/index.d.ts

@@ -837,6 +837,58 @@ interface Transport {
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
 }
+/** How a worker decides its concurrency, carried in {@link WorkerStatus} so a dashboard can tell a
+ *  fixed knob from a self-regulating one (and, for the latter, where the controller currently sits). */
+interface WorkerConcurrencyStatus {
+    /** `fixed` = the configured `concurrency` number, never moves. `adaptive` = the controller tunes it. */
+    mode: 'fixed' | 'adaptive';
+    /** The concurrency ceiling in effect right now (fixed: the configured value; adaptive: the live limit). */
+    limit: number;
+    /** Adaptive only — the floor the controller won't go below. */
+    min?: number;
+    /** Adaptive only — the ceiling the controller won't exceed. */
+    max?: number;
+}
+/** The adaptive controller's most recent limit change — the "why did it move" a dashboard shows so an
+ *  auto-tuner isn't a black box. Absent until the controller first adjusts (or for a fixed worker). */
+interface WorkerAdjust {
+    /** Epoch ms of the adjustment. */
+    at: number;
+    /** Limit before this change. */
+    from: number;
+    /** Limit after this change. */
+    to: number;
+    /** Why it moved: `ram_ceiling` (hard brake), `backpressure` (errors/stall), `grow` (had headroom),
+     *  `shrink` (latency gradient showed queuing), `cpu_ceiling`. */
+    reason: 'ram_ceiling' | 'cpu_ceiling' | 'backpressure' | 'grow' | 'shrink';
+}
+/** A live snapshot of a worker's execution state, carried in the worker-liveness heartbeat (so it
+ *  rides the existing TTL'd key — no extra round-trip) and surfaced per worker in the dashboard. Every
+ *  field beyond {@link concurrency}/{@link inFlight} is best-effort: a field a runtime can't measure is
+ *  simply omitted. The shape is shared by the TS and Python SDKs so a mixed-language group reports
+ *  uniformly. */
+interface WorkerStatus {
+    /** Which SDK is running this worker — `node` (TS) or `python`. */
+    runtime?: 'node' | 'python';
+    /** The worker's concurrency knob and its live ceiling. */
+    concurrency: WorkerConcurrencyStatus;
+    /** Tasks executing right now (0..limit). With `limit`, this is the saturation a dashboard charts. */
+    inFlight: number;
+    /** Resident set size in bytes, if the runtime can read it. */
+    rssBytes?: number;
+    /** The process memory ceiling in bytes (cgroup `memory.max`, else host total), if known. */
+    rssLimitBytes?: number;
+    /** RSS as a percent of {@link rssLimitBytes} (0..100) — what the adaptive RAM brake watches. */
+    rssPct?: number;
+    /** Process CPU utilisation percent over the last control tick (0..100×cores), if measured. */
+    cpuPct?: number;
+    /** Completed tasks per minute over the recent window — the controller's throughput signal. */
+    throughputPerMin?: number;
+    /** p95 of recent task durations in ms — the latency a dashboard charts against the limit. */
+    p95Ms?: number;
+    /** The adaptive controller's last limit change (absent for a fixed worker or before the first move). */
+    lastAdjust?: WorkerAdjust;
+}
 /** One worker's liveness record — a TTL'd heartbeat a worker refreshes while it's consuming. Its
  *  ABSENCE (the key expired) is the signal: a worker that died or stalled stops refreshing. */
 interface WorkerHeartbeat {
@@ -846,6 +898,9 @@ interface WorkerHeartbeat {
     instanceId: string;
     /** Epoch ms of the worker's most recent heartbeat. */
     lastBeatAt: number;
+    /** The worker's live execution snapshot, when its heartbeat carries one (newer SDKs stamp a JSON
+     *  value; an older SDK's bare-timestamp heartbeat leaves this undefined). */
+    status?: WorkerStatus;
 }
 /** Per-group worker-health snapshot: how much work is queued vs. how many workers are alive to do it.
  *  The actionable alert state is `depth > 0 && liveWorkers.length === 0` — work piling up with no
@@ -1581,6 +1636,29 @@ declare class WorkflowEngine {
         executionTimeout?: string | number;
         validateInput?: (input: unknown) => void | Promise<void>;
     }): void;
+    /**
+     * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+     * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+     * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+     * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+     * `engine.remote('processing', { group: 'processing' })` instead of
+     * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+     *
+     * Defaults the version to `'1'`. All the other {@link registerRemote} options
+     * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+     * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+     * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+     */
+    remote(name: string, opts: {
+        /** Worker group this workflow's turns are dispatched to (also the executor's target group). */
+        group: string;
+        /** Workflow version. Defaults to `'1'`. */
+        version?: string;
+        tags?: string[];
+        singleton?: SingletonConfig;
+        executionTimeout?: string | number;
+        validateInput?: (input: unknown) => void | Promise<void>;
+    }): void;
     /**
      * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
      * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
@@ -2496,4 +2574,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };

package/dist/index.js

@@ -700,6 +700,70 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
+// src/remote-workflow-executor.ts
+var taskCounter = 0;
+var RemoteWorkflowExecutor = class {
+  static {
+    __name(this, "RemoteWorkflowExecutor");
+  }
+  transport;
+  group;
+  opts;
+  pending = /* @__PURE__ */ new Map();
+  subscribed = false;
+  constructor(transport, group, opts = {}) {
+    this.transport = transport;
+    this.group = group;
+    this.opts = opts;
+  }
+  ensureSubscribed() {
+    if (this.subscribed) return;
+    if (!this.transport.onDecision) {
+      throw new Error("transport does not support workflow decisions (onDecision)");
+    }
+    this.subscribed = true;
+    this.transport.onDecision(async (decision) => {
+      const resolve = this.pending.get(decision.taskId);
+      if (resolve) {
+        this.pending.delete(decision.taskId);
+        resolve(decision);
+      }
+    });
+  }
+  async advance(run, history) {
+    if (!this.transport.dispatchWorkflowTask) {
+      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
+    }
+    this.ensureSubscribed();
+    taskCounter += 1;
+    const taskId = `${run.id}:wf:${taskCounter}`;
+    const task = {
+      taskId,
+      runId: run.id,
+      workflow: run.workflow,
+      workflowVersion: run.workflowVersion,
+      input: run.input,
+      history,
+      group: this.group,
+      priority: run.priority,
+      attempt: 1
+    };
+    const decision = new Promise((resolve, reject) => {
+      this.pending.set(taskId, resolve);
+      const { timeoutMs } = this.opts;
+      if (timeoutMs) {
+        const timer = setTimeout(() => {
+          this.pending.delete(taskId);
+          reject(new RemoteWorkflowTimeout(taskId, timeoutMs));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+    });
+    await this.transport.dispatchWorkflowTask(task);
+    return decision;
+  }
+};
+
 // src/singleton-gate.ts
 var SINGLETON_RETRY_MS = 1e3;
 var SINGLETON_RETRY_JITTER_MS = 250;
@@ -801,6 +865,19 @@ var TransportPool = class {
   get size() {
     return this.transports.length;
   }
+  /**
+  * The primary (first) transport — the one `dispatch` prefers when no `preferId` is pinned. A
+  * {@link RemoteWorkflowExecutor} built by `engine.remote()` rides it (it needs a single
+  * `dispatchWorkflowTask`/`onDecision` Transport, not the whole failover pool). Throws if the pool
+  * is empty — there is nothing to dispatch a remote workflow over.
+  */
+  get primary() {
+    const first = this.transports[0];
+    if (!first) {
+      throw new Error("no transport configured \u2014 engine.remote() needs a transport (or transports)");
+    }
+    return first.transport;
+  }
   /** Register the engine's result/heartbeat/step-event handlers on EVERY transport — a result can come
   *  back on whichever one delivered the task, so failover stays symmetric. `onStepEvent` is wired only
   *  on transports that carry streamed workflow step lifecycle (BullMQ); others simply skip it. */
@@ -1720,6 +1797,28 @@ var WorkflowEngine = class {
     if (!current || isNewerVersion(version, current.version)) this.latest.set(name, registered);
   }
   /**
+  * The convenience form of {@link registerRemote}: register a workflow whose body runs on a worker
+  * `group` (e.g. the Python `durable-worker`, or a separate TS worker), without hand-building a
+  * {@link RemoteWorkflowExecutor}. It wires the standard broker executor — a `RemoteWorkflowExecutor`
+  * over the engine's own transport, dispatching to `opts.group` — for you, so you write
+  * `engine.remote('processing', { group: 'processing' })` instead of
+  * `engine.registerRemote('processing', '1', { group: 'processing', executor: new RemoteWorkflowExecutor(transport, 'processing') })`.
+  *
+  * Defaults the version to `'1'`. All the other {@link registerRemote} options
+  * (`tags` / `singleton` / `executionTimeout` / `validateInput`) pass straight through. Reach for the
+  * low-level {@link registerRemote} when you need a custom {@link WorkflowExecutor} (a different
+  * transport, a fixed `timeoutMs`, a polyglot stub) — `remote()` is the standard wiring on the rails.
+  */
+  remote(name, opts) {
+    const { group, version, ...rest } = opts;
+    const executor = new RemoteWorkflowExecutor(this.pool.primary, group);
+    this.registerRemote(name, version ?? "1", {
+      group,
+      executor,
+      ...rest
+    });
+  }
+  /**
   * Register a flow-control queue referenced by `ctx.call(step, input, { queue })`. Caps concurrent
   * in-flight steps and/or the admission rate; blocked calls re-suspend and retry, so the limit is
   * durable. Per engine instance (see {@link QueueConfig}). Registering the same name replaces it.
@@ -3615,70 +3714,6 @@ function remoteStep(config) {
 }
 __name(remoteStep, "remoteStep");
 
-// src/remote-workflow-executor.ts
-var taskCounter = 0;
-var RemoteWorkflowExecutor = class {
-  static {
-    __name(this, "RemoteWorkflowExecutor");
-  }
-  transport;
-  group;
-  opts;
-  pending = /* @__PURE__ */ new Map();
-  subscribed = false;
-  constructor(transport, group, opts = {}) {
-    this.transport = transport;
-    this.group = group;
-    this.opts = opts;
-  }
-  ensureSubscribed() {
-    if (this.subscribed) return;
-    if (!this.transport.onDecision) {
-      throw new Error("transport does not support workflow decisions (onDecision)");
-    }
-    this.subscribed = true;
-    this.transport.onDecision(async (decision) => {
-      const resolve = this.pending.get(decision.taskId);
-      if (resolve) {
-        this.pending.delete(decision.taskId);
-        resolve(decision);
-      }
-    });
-  }
-  async advance(run, history) {
-    if (!this.transport.dispatchWorkflowTask) {
-      throw new Error("transport does not support workflow tasks (dispatchWorkflowTask)");
-    }
-    this.ensureSubscribed();
-    taskCounter += 1;
-    const taskId = `${run.id}:wf:${taskCounter}`;
-    const task = {
-      taskId,
-      runId: run.id,
-      workflow: run.workflow,
-      workflowVersion: run.workflowVersion,
-      input: run.input,
-      history,
-      group: this.group,
-      priority: run.priority,
-      attempt: 1
-    };
-    const decision = new Promise((resolve, reject) => {
-      this.pending.set(taskId, resolve);
-      const { timeoutMs } = this.opts;
-      if (timeoutMs) {
-        const timer = setTimeout(() => {
-          this.pending.delete(taskId);
-          reject(new RemoteWorkflowTimeout(taskId, timeoutMs));
-        }, timeoutMs);
-        timer.unref?.();
-      }
-    });
-    await this.transport.dispatchWorkflowTask(task);
-    return decision;
-  }
-};
-
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {