@lostgradient/weft 0.2.0

package/dist/testing/test-engine.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Test-oriented Engine subclass with virtual time control and activity mocking.
+ *
+ * Wraps Engine with a MemoryStorage, TimeControl, and ActivityMockRegistry
+ * so tests can advance time deterministically and substitute activity
+ * implementations without touching real infrastructure.
+ *
+ * @module testing/test-engine
+ */
+import { Engine } from '../core/engine.ts';
+import type { Duration } from '../core/types.ts';
+import { MemoryStorage } from '../storage/memory.ts';
+import type { ChaosScenario, FailureCategory } from './chaos.ts';
+import type { MockHandle } from './mocks.ts';
+import { ActivityMockRegistry } from './mocks.ts';
+/**
+ * Options for {@link TestEngine.runN}.
+ *
+ * @example
+ * ```ts
+ * import { TestEngine, type RunNOptions } from '@lostgradient/weft/testing';
+ *
+ * const options: RunNOptions = {
+ *   runs: 50,
+ *   chaos: { faultRate: 0.2, faults: ['transient'], seed: 7 },
+ * };
+ * const engine = new TestEngine();
+ * // const result = await engine.runN('my-workflow', {}, options);
+ * ```
+ */
+export interface RunNOptions {
+    /** Number of independent runs to execute. */
+    runs: number;
+    /** Optional chaos scenario to apply across all runs. */
+    chaos?: ChaosScenario;
+}
+/**
+ * Aggregate reliability metrics returned by {@link TestEngine.runN}.
+ *
+ * @example
+ * ```ts
+ * import { workflow } from '@lostgradient/weft';
+ * import { TestEngine, type RunNResult } from '@lostgradient/weft/testing';
+ *
+ * const ping = workflow({ name: 'ping' }).execute(async function* () { return 'pong'; });
+ * const engine = new TestEngine();
+ * engine.register(ping);
+ * const result: RunNResult = await engine.runN('ping', null, { runs: 10 });
+ * console.log(result.passRate);    // 1 (all passed)
+ * console.log(result.consistency); // 1 (all identical)
+ * ```
+ */
+export interface RunNResult {
+    /** Fraction of runs [0, 1] that completed successfully. */
+    passRate: number;
+    /**
+     * Fraction of successful runs [0, 1] that returned the same output as the
+     * first successful run. `1.0` means all successes were identical.
+     * `NaN` if there were no successful runs.
+     */
+    consistency: number;
+    /** Count of failures bucketed by failure category. */
+    categories: Record<FailureCategory, number>;
+}
+/**
+ * Test-oriented {@link Engine} subclass with virtual time control and
+ * activity mocking for deterministic, fast workflow tests.
+ *
+ * Wraps the engine with a {@link MemoryStorage}, a {@link TimeControl}
+ * instance, and an {@link ActivityMockRegistry}.  Use `engine.mock(activityFn,
+ * impl)` to replace real activities with stubs, and
+ * `await engine.advanceTime('5m')` to advance virtual time without waiting on
+ * real timers.
+ *
+ * @example
+ * ```ts
+ * import { workflow, type WorkflowContext } from '@lostgradient/weft';
+ * import { TestEngine } from '@lostgradient/weft/testing';
+ *
+ * const engine = new TestEngine();
+ *
+ * async function fetchPrice(ticker: unknown): Promise<number> {
+ *   return 0; // real implementation
+ * }
+ *
+ * const mock = engine.mock(fetchPrice, async (_ticker: unknown) => 42);
+ * const priceCheck = workflow({ name: 'price-check' }).execute(
+ *   async function* (_ctx: WorkflowContext, _input: unknown) {
+ *     return 42; // simplified test example
+ *   },
+ * );
+ * engine.register(priceCheck);
+ *
+ * const handle = await engine.start('price-check', 'ACME');
+ * console.log(await handle.result()); // 42
+ * console.log(mock.callCount); // 0
+ * ```
+ */
+export declare class TestEngine extends Engine {
+    #private;
+    constructor(options?: {
+        startTime?: number;
+    });
+    /**
+     * Advance virtual time by the given duration. Fires any scheduler
+     * timers that fall within the advanced window.
+     */
+    advanceTime(duration: Duration): Promise<void>;
+    /** Current virtual time in milliseconds since epoch. */
+    get now(): number;
+    /**
+     * Register a mock implementation for an activity function.
+     * When the engine encounters this activity, it will call the mock instead.
+     */
+    mock<TResult>(activity: () => Promise<TResult> | TResult, implementation: () => TResult | Promise<TResult>): MockHandle<void, TResult>;
+    mock<TInput, TResult>(activity: (input: TInput) => Promise<TResult> | TResult, implementation: (input: TInput) => TResult | Promise<TResult>): MockHandle<TInput, TResult>;
+    /**
+     * Create a new TestEngine backed by the same storage, simulating
+     * engine recovery (like a process restart). The new engine sees all
+     * persisted state but has fresh in-memory structures.
+     */
+    recover(): TestEngine;
+    /** Direct access to the underlying MemoryStorage for assertions. */
+    get storage(): MemoryStorage;
+    /** Direct access to mock registry. */
+    get mocks(): ActivityMockRegistry;
+    /**
+     * Run the named workflow N times and return aggregate reliability metrics.
+     *
+     * Runs are serial and independent. If a `chaos` scenario is provided, each
+     * registered activity mock is temporarily wrapped with `withChaos` for the
+     * duration of that run, then restored. This ensures that the workflow
+     * functions — which close over `this` engine's mock registry — observe the
+     * chaos-injected implementations during each run.
+     *
+     * Workflow state isolation is achieved by using unique per-run workflow IDs,
+     * so previous results do not influence subsequent runs.
+     *
+     * @param type    The registered workflow type name.
+     * @param input   Input passed to each run.
+     * @param options `{ runs, chaos? }` — number of runs and optional scenario.
+     * @returns       `{ passRate, consistency, categories }` aggregate metrics.
+     */
+    runN(type: string, input: unknown, options: RunNOptions): Promise<RunNResult>;
+}

package/dist/testing/test-engine.js

@@ -0,0 +1,147 @@
+import { Engine } from "../core/engine.js";
+import { runtimeWorkflowEngine } from "../core/runtime-workflow-engine.js";
+import { parseDuration } from "../core/scheduler.js";
+import { activity as defineActivity } from "../core/types.js";
+import { MemoryStorage } from "../storage/memory.js";
+import { withChaos } from "./chaos.js";
+import { yieldToPortableEventLoop } from "./event-loop.js";
+import { ActivityMockRegistry } from "./mocks.js";
+import { TimeControl } from "./time-control.js";
+function activityRegistrationOptionsFromMetadata(metadata) {
+  return {
+    queue: metadata.queue,
+    ...metadata.description === void 0 ? {} : { description: metadata.description },
+    ...metadata.tags === void 0 ? {} : { tags: [...metadata.tags] },
+    ...metadata.inputSchema === void 0 ? {} : { inputSchema: metadata.inputSchema },
+    ...metadata.outputSchema === void 0 ? {} : { outputSchema: metadata.outputSchema },
+    ...metadata.retry === void 0 ? {} : { retry: metadata.retry },
+    ...metadata.timeout === void 0 ? {} : { timeout: metadata.timeout },
+    ...metadata.idempotent === void 0 ? {} : { idempotent: metadata.idempotent }
+  };
+}
+
+export class TestEngine extends Engine {
+  #timeControl;
+  #mocks;
+  #memoryStorage;
+  constructor(options) {
+    const storage = new MemoryStorage, timeControl = new TimeControl(options?.startTime);
+    super({
+      storage,
+      getNow: () => timeControl.now
+    });
+    this.#timeControl = timeControl;
+    this.#mocks = new ActivityMockRegistry;
+    this.#memoryStorage = storage;
+  }
+  async advanceTime(duration) {
+    const milliseconds = parseDuration(duration), target = this.#timeControl.now + milliseconds;
+    await this.#timeControl.advance(duration);
+    await yieldToPortableEventLoop();
+    for (let i = 0;i < 4; i++)
+      await Promise.resolve();
+    await this.scheduler.tick(target);
+    for (let i = 0;i < 3; i++)
+      await Promise.resolve();
+    for (let i = 0;i < 3; i++)
+      await yieldToPortableEventLoop();
+  }
+  get now() {
+    return this.#timeControl.now;
+  }
+  mock(activity, implementation) {
+    const activityName = activity.name || "anonymous";
+    if (this.#mocks.hasRestoreHook(activity))
+      return this.#mocks.mock(activity, implementation);
+    const previousRegistration = this.#captureActivityRegistration(activityName), handle = this.#mocks.mock(activity, implementation), mockedActivity = defineActivity({
+      name: activityName,
+      execute: async (input) => {
+        const mocked = this.#mocks.get(activity);
+        if (mocked)
+          return await mocked.implementation(input);
+        return await activity(input);
+      }
+    });
+    this.register(mockedActivity);
+    this.#mocks.onRestore(activity, () => this.#restoreActivityRegistration(activityName, previousRegistration));
+    return handle;
+  }
+  #restoreActivityRegistration(activityName, previousRegistration) {
+    if (previousRegistration)
+      this.registerActivityFunction(activityName, previousRegistration.fn, previousRegistration.options);
+    else
+      this.unregisterRegisteredActivity(activityName);
+  }
+  #captureActivityRegistration(activityName) {
+    const fn = this.resolveRegisteredActivity(activityName), metadata = this.getActivityDefinition(activityName);
+    if (!fn || !metadata)
+      return;
+    return {
+      fn,
+      options: activityRegistrationOptionsFromMetadata(metadata)
+    };
+  }
+  recover() {
+    const recovered = new TestEngine({ startTime: this.#timeControl.now }), snapshot = this.#memoryStorage.snapshot();
+    for (const [key, value] of snapshot)
+      recovered.#memoryStorage.put(key, value);
+    return recovered;
+  }
+  get storage() {
+    return this.#memoryStorage;
+  }
+  get mocks() {
+    return this.#mocks;
+  }
+  async runN(type, input, options) {
+    const { runs, chaos } = options;
+    let passes = 0;
+    const successOutputs = [], categories = {
+      application: 0,
+      timeout: 0,
+      cancellation: 0,
+      resource: 0,
+      system: 0
+    };
+    for (let i = 0;i < runs; i++) {
+      const saved = wrapMocksWithChaos(this.#mocks, chaos, i), runId = `runN-${type}-${i}-${Date.now()}`;
+      try {
+        const output = await (await runtimeWorkflowEngine(this).start(type, input, { id: runId })).result();
+        passes++;
+        successOutputs.push(output);
+      } catch {
+        const category = (await this.get(runId))?.failureCategory ?? "system";
+        categories[category]++;
+      } finally {
+        restoreMocks(this.#mocks, saved);
+      }
+    }
+    const passRate = runs > 0 ? passes / runs : 0, consistency = computeConsistency(successOutputs);
+    return { passRate, consistency, categories };
+  }
+}
+function wrapMocksWithChaos(registry, chaos, runIndex) {
+  const saved = new Map;
+  if (!chaos)
+    return saved;
+  for (const [activity, mocked] of registry.entries()) {
+    const original = mocked.handle.currentImplementation;
+    saved.set(activity, original);
+    const perRunChaos = chaos.seed !== void 0 ? { ...chaos, seed: chaos.seed + runIndex } : chaos, chaosWrapped = withChaos((activityInput) => original(activityInput), perRunChaos);
+    mocked.handle.mockImplementation((activityInput) => chaosWrapped(activityInput));
+  }
+  return saved;
+}
+function restoreMocks(registry, saved) {
+  for (const [activity, mocked] of registry.entries()) {
+    const original = saved.get(activity);
+    if (original !== void 0)
+      mocked.handle.mockImplementation(original);
+  }
+}
+function computeConsistency(outputs) {
+  if (outputs.length === 0)
+    return NaN;
+  const firstOutput = JSON.stringify(outputs[0]);
+  return outputs.filter((out) => JSON.stringify(out) === firstOutput).length / outputs.length;
+}

package/dist/testing/time-control.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic virtual clock for testing durable workflows.
+ *
+ * Does NOT monkey-patch global timers. Instead, provides an explicit
+ * `now` property and a `schedule` method for registering timer callbacks
+ * that fire when virtual time is advanced past their target.
+ *
+ * @module testing/time-control
+ */
+import type { Duration } from '../core/types';
+/**
+ * Deterministic virtual clock for testing durable workflows that depend on
+ * time-based behaviour (timers, delays, scheduling).
+ *
+ * Does NOT monkey-patch global timers.  Instead, provides an explicit `now`
+ * property and an `advance` method that fires registered callbacks in
+ * chronological order as virtual time moves forward.  Use this inside a
+ * {@link TestEngine} to write fully deterministic timer tests.
+ *
+ * @example
+ * ```ts
+ * import { TimeControl } from '@lostgradient/weft/testing';
+ *
+ * const clock = new TimeControl(0);
+ * let fired = false;
+ *
+ * clock.schedule(5_000, () => {
+ *   fired = true;
+ * });
+ *
+ * await clock.advance('5s');
+ * console.log(fired);   // true
+ * console.log(clock.now); // 5000
+ * ```
+ */
+export declare class TimeControl {
+    #private;
+    constructor(startTime?: number);
+    /** Current virtual time in milliseconds since epoch. */
+    get now(): number;
+    /**
+     * Advance time by duration. Fires all timers that fall within the
+     * window, in chronological order.
+     */
+    advance(duration: Duration): Promise<void>;
+    /** Advance time to a specific timestamp. Throws if in the past. */
+    advanceTo(timestamp: number): Promise<void>;
+    /**
+     * Schedule a timer callback at a specific virtual time.
+     * Returns a cancel function.
+     */
+    schedule(fireAt: number, callback: () => void | Promise<void>): () => void;
+    /** Number of pending (non-cancelled, not-yet-fired) timers. */
+    get pendingTimerCount(): number;
+    /** Peek at the next timer's fire time. */
+    get nextTimerAt(): number | undefined;
+    /** Reset to initial state. */
+    reset(startTime?: number): void;
+}

package/dist/testing/time-control.js

@@ -0,0 +1,68 @@
+import { parseDuration } from "../core/scheduler.js";
+
+export class TimeControl {
+  #currentTime;
+  #timers;
+  #nextId;
+  constructor(startTime) {
+    this.#currentTime = startTime ?? Date.now();
+    this.#timers = [];
+    this.#nextId = 1;
+  }
+  get now() {
+    return this.#currentTime;
+  }
+  async advance(duration) {
+    const target = this.#currentTime + parseDuration(duration);
+    await this.#fireTimersUpTo(target);
+    this.#currentTime = target;
+  }
+  async advanceTo(timestamp) {
+    if (timestamp < this.#currentTime)
+      throw Error(`Cannot advance to ${timestamp}: current time is already ${this.#currentTime}`);
+    await this.#fireTimersUpTo(timestamp);
+    this.#currentTime = timestamp;
+  }
+  schedule(fireAt, callback) {
+    const timer = {
+      fireAt,
+      callback,
+      id: this.#nextId++,
+      cancelled: !1
+    };
+    this.#timers.push(timer);
+    return () => {
+      timer.cancelled = !0;
+    };
+  }
+  get pendingTimerCount() {
+    return this.#timers.filter((timer) => !timer.cancelled).length;
+  }
+  get nextTimerAt() {
+    return this.#timers.filter((timer) => !timer.cancelled).toSorted((a, b) => a.fireAt - b.fireAt)[0]?.fireAt;
+  }
+  reset(startTime) {
+    this.#currentTime = startTime ?? Date.now();
+    this.#timers = [];
+    this.#nextId = 1;
+  }
+  async#fireTimersUpTo(target) {
+    for (;; ) {
+      let earliest, earliestIndex = -1;
+      for (let i = 0;i < this.#timers.length; i++) {
+        const timer = this.#timers[i];
+        if (timer.cancelled || timer.fireAt > target)
+          continue;
+        if (earliest === void 0 || timer.fireAt < earliest.fireAt) {
+          earliest = timer;
+          earliestIndex = i;
+        }
+      }
+      if (earliest === void 0)
+        break;
+      this.#timers.splice(earliestIndex, 1);
+      this.#currentTime = earliest.fireAt;
+      await earliest.callback();
+    }
+  }
+}

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Current Weft package version. Useful for diagnostics, telemetry, discovery
+ * documents, and verifying which build is running.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from '@lostgradient/weft';
+ *
+ * console.log(`Running Weft ${VERSION}`);
+ * ```
+ */
+export declare const VERSION = "0.2.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = "0.2.0";

package/dist/worker/activity-table.d.ts

@@ -0,0 +1,33 @@
+import { type RemoteWorkerJsonValue } from './protocol.ts';
+import { type RemoteWorkerActivityFunction, type RemoteWorkerWorkflowDefinition } from './workflow-activity-binding.ts';
+/**
+ * The subset of worker options that determines the advertised activity table.
+ *
+ * `workflows` is required on the public {@link RemoteWorkerOptions}. It stays
+ * optional here so {@link resolveActivityTable} can defend against untyped or
+ * JavaScript callers that omit it and throw a clear construction error rather
+ * than reading `undefined`. This optionality must not leak into the public
+ * constructor type.
+ */
+export type ActivityTableSource = {
+    workflows?: Record<string, RemoteWorkerWorkflowDefinition>;
+};
+/**
+ * Coerce an activity's return value into a JSON value safe to send over the
+ * wire. `undefined`, non-serializable values, and anything that does not round
+ * -trip through JSON collapse to `null`.
+ */
+export declare function normalizeWorkerJsonValue(value: unknown): RemoteWorkerJsonValue;
+/**
+ * Resolve the activity table the worker will advertise and dispatch against.
+ *
+ * Centralises the precondition checks so name-grammar violations and
+ * key/name mismatches fail fast at construction time, before any WebSocket
+ * connection is opened. `workflows` is required.
+ *
+ * The removed `activities` alias is rejected actively rather than ignored: an
+ * untyped or JavaScript caller that still passes it (especially alongside an
+ * empty `workflows: {}`) would otherwise build a worker that silently drops part
+ * of its configuration, so we fail loudly instead.
+ */
+export declare function resolveActivityTable(options: ActivityTableSource): Record<string, RemoteWorkerActivityFunction>;

package/dist/worker/activity-table.js

@@ -0,0 +1,20 @@
+import { isRemoteWorkerJsonValue } from "./protocol.js";
+import {
+  buildQualifiedActivityTable
+} from "./workflow-activity-binding.js";
+export function normalizeWorkerJsonValue(value) {
+  if (value === void 0)
+    return null;
+  const encoded = JSON.stringify(value);
+  if (encoded === void 0)
+    return null;
+  const parsed = JSON.parse(encoded);
+  return isRemoteWorkerJsonValue(parsed) ? parsed : null;
+}
+export function resolveActivityTable(options) {
+  if (Object.prototype.hasOwnProperty.call(options, "activities"))
+    throw Error("RemoteWorker no longer accepts `activities`; declare your activities under `workflows` instead.");
+  if (options.workflows === void 0 || options.workflows === null)
+    throw Error("RemoteWorker requires `workflows` \u2014 a map of workflow type \u2192 { name, activities }.");
+  return buildQualifiedActivityTable(options.workflows);
+}

package/dist/worker/execute-with-interceptors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared utility for executing activities through an optional interceptor chain.
+ * Used by both RemoteWorker (WebSocket) and LongPollWorker (HTTP).
+ */
+import type { ActivityInterceptor } from '../core/interceptor.ts';
+import { composeActivityInterceptors } from '../core/interceptor.ts';
+export interface TaskInfo {
+    activityName: string;
+    operationId: string;
+    attempt?: number;
+    input: unknown;
+    headers?: Record<string, string>;
+}
+export interface ComposedInterceptor {
+    execute: ReturnType<typeof composeActivityInterceptors>['execute'];
+}
+/**
+ * Pre-compose interceptors once (at construction time) so the chain
+ * is not rebuilt on every task execution.
+ */
+export declare function buildComposedInterceptor(interceptors: ActivityInterceptor[] | undefined): ComposedInterceptor | null;
+/**
+ * Execute an activity function, optionally wrapped by a pre-composed interceptor chain.
+ * Provides a consistent AbortSignal and headers Map to the interception context.
+ */
+export declare function executeWithInterceptors(activityFunction: (input: unknown, context?: {
+    signal: AbortSignal;
+}) => Promise<unknown>, task: TaskInfo, composed: ComposedInterceptor | null, signal?: AbortSignal): Promise<unknown>;

package/dist/worker/execute-with-interceptors.js

@@ -0,0 +1,21 @@
+import { composeActivityInterceptors } from "../core/interceptor.js";
+export function buildComposedInterceptor(interceptors) {
+  if (!interceptors || interceptors.length === 0)
+    return null;
+  return composeActivityInterceptors(interceptors);
+}
+export async function executeWithInterceptors(activityFunction, task, composed, signal) {
+  if (!composed)
+    return activityFunction(task.input, signal ? { signal } : void 0);
+  const headers = new Map(Object.entries(task.headers ?? {}));
+  return composed.execute({
+    activityName: task.activityName,
+    operationId: task.operationId,
+    attempt: task.attempt ?? 1,
+    input: task.input,
+    headers,
+    ...signal && { signal }
+  }, async (interception) => {
+    return activityFunction(interception.input, signal ? { signal } : void 0);
+  });
+}

package/dist/worker/heartbeat.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Sends periodic keepalive heartbeats from a remote worker to the server to
+ * extend the task visibility timeout while activity execution is in progress.
+ *
+ * Construct with a `sendHeartbeat` callback (typically the worker's WebSocket
+ * send function) and an optional interval in milliseconds (default: 10 000).
+ * Call `start()` when a task is acquired and `stop()` when it completes.
+ *
+ * @example
+ * ```ts
+ * import { HeartbeatManager } from '@lostgradient/weft';
+ *
+ * let heartbeatFn = (details?: unknown) => {
+ *   console.log('heartbeat', details);
+ * };
+ *
+ * const manager = new HeartbeatManager(heartbeatFn, 5_000);
+ * manager.start();
+ * // ... execute long-running activity ...
+ * manager.beat({ progress: 0.5 }); // one-off heartbeat with details
+ * manager.stop();
+ * ```
+ */
+export declare class HeartbeatManager {
+    #private;
+    constructor(sendHeartbeat: (details?: unknown) => void, intervalMs?: number);
+    /** Start sending periodic heartbeats. */
+    start(): void;
+    /** Stop sending heartbeats. */
+    stop(): void;
+    /** Send a one-off heartbeat with optional details. */
+    beat(details?: unknown): void;
+    get isRunning(): boolean;
+}

package/dist/worker/heartbeat.js

@@ -0,0 +1,31 @@
+const DEFAULT_INTERVAL_MS = 1e4;
+
+export class HeartbeatManager {
+  #interval;
+  #sendHeartbeat;
+  #intervalMs;
+  constructor(sendHeartbeat, intervalMs) {
+    this.#sendHeartbeat = sendHeartbeat;
+    this.#intervalMs = intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.#interval = null;
+  }
+  start() {
+    if (this.#interval !== null)
+      return;
+    this.#interval = setInterval(() => {
+      this.#sendHeartbeat();
+    }, this.#intervalMs);
+  }
+  stop() {
+    if (this.#interval !== null) {
+      clearInterval(this.#interval);
+      this.#interval = null;
+    }
+  }
+  beat(details) {
+    this.#sendHeartbeat(details);
+  }
+  get isRunning() {
+    return this.#interval !== null;
+  }
+}

package/dist/worker/index.d.ts

@@ -0,0 +1,57 @@
+import { type InternalRemoteWorkerOptions } from './options.ts';
+export type { RemoteWorkerOptions } from './options.ts';
+export { isOutboxFull, MAX_BUFFERED_TASK_RESULTS } from './task-result-outbox.ts';
+export { HeartbeatManager } from './heartbeat.ts';
+export { LongPollWorker } from './long-poll.ts';
+export type { LongPollWorkerOptions } from './long-poll.ts';
+export { WorkerRegistry } from './registry.ts';
+export type { InFlightTask, RoutingOptions, WorkerInfo } from './registry.ts';
+export type { RemoteActivityContext } from './remote-activity-context.ts';
+export { buildQualifiedActivityTable, type RemoteWorkerActivityFunction, type RemoteWorkerActivityImplementation, type RemoteWorkerWorkflowDefinition, } from './workflow-activity-binding.ts';
+/**
+ * WebSocket-based remote worker that connects to the Weft server and executes
+ * activities on behalf of the engine.
+ *
+ * Construct with the server URL, a map of activity implementations, and optional
+ * concurrency and queue settings.  Call `start()` to open the WebSocket
+ * connection and begin processing tasks.  Dispose the instance (or call
+ * `[Symbol.dispose]()`) to close the connection.
+ *
+ * @example
+ * ```ts
+ * import { RemoteWorker } from '@lostgradient/weft';
+ *
+ * using worker = new RemoteWorker({
+ *   serverUrl: 'ws://localhost:3000',
+ *   workflows: {
+ *     notifications: {
+ *       name: 'notifications',
+ *       activities: {
+ *         sendEmail: async (input: unknown) => {
+ *           console.log('sending', input);
+ *           return 'sent';
+ *         },
+ *       },
+ *     },
+ *   },
+ *   concurrency: 5,
+ *   queue: 'email',
+ * });
+ * await worker.connect();
+ * ```
+ */
+export declare class RemoteWorker implements Disposable {
+    #private;
+    constructor(options: InternalRemoteWorkerOptions);
+    /** Connect to the server and start processing tasks. */
+    connect(): Promise<void>;
+    /** Gracefully disconnect: finish in-flight, then close. */
+    disconnect(): Promise<void>;
+    /** Get the number of in-flight tasks. */
+    get inFlight(): number;
+    /** Whether the worker is connected. */
+    get connected(): boolean;
+    /** Whether the worker is in the process of shutting down. */
+    get shuttingDown(): boolean;
+    [Symbol.dispose](): void;
+}