@lostgradient/weft 0.2.0

package/dist/client/event-stream-transport.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Transport plumbing for the {@link WorkflowEventSubscription}: the minimal
+ * socket surface it drives, the watch-channel URL builder, the default
+ * `WebSocket` factory (Bun vs. browser), and the frame parsing / overlap-dedup
+ * helpers. Kept separate from the subscription state machine so each file stays
+ * small and the pure helpers are independently testable.
+ *
+ * @module client/event-stream-transport
+ */
+import type { WorkflowEvent } from '../core/types.ts';
+/** Minimal socket surface the subscription drives. Matches `WebSocket`. */
+export type StreamSocket = {
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open', listener: () => void): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'close', listener: () => void): void;
+    addEventListener(type: 'error', listener: (event: unknown) => void): void;
+};
+/** Builds a {@link StreamSocket} for a `ws(s)://…/watch` URL with headers. */
+export type WebSocketFactory = (url: string, headers: Record<string, string>) => StreamSocket;
+/**
+ * Build the absolute `ws(s)://…/v1/workflows/:id/watch` URL for a workflow's
+ * live event channel from a client base URL.
+ *
+ * An absolute `http(s)://…` base URL has its scheme swapped to `ws(s):`. A
+ * relative base URL (`''`, `'/'`, `'/weft'` — the forms browser and
+ * service-worker deployments use, where REST `fetch` resolves against the page
+ * origin) is resolved against `globalThis.location` so the result is always the
+ * absolute URL the `WebSocket` constructor requires. When no `location` is
+ * available (e.g. a non-browser runtime given a relative base), the relative
+ * base is returned unchanged — the same input REST `fetch` would also reject.
+ */
+export declare function workflowWatchWebSocketUrl(baseUrl: string, workflowId: string): string;
+/**
+ * The default factory. Under Bun the second `WebSocket` argument is an options
+ * bag that accepts custom upgrade headers, so auth headers ride the handshake.
+ * Elsewhere the second argument is `protocols` (a string or string array) and
+ * the platform `WebSocket` cannot send custom headers at all, so we construct
+ * with the URL alone:
+ *
+ *   - In a browser / service worker that is expected — cross-origin auth rides a
+ *     cookie or query param the server accepts, not a WebSocket header.
+ *   - In Node/edge the global `WebSocket` (Node 22+, undici) also cannot send
+ *     headers, so silently dropping a configured `Authorization`/`token` would
+ *     produce an unauthenticated socket that fails or reconnects forever against
+ *     an auth-enabled server. That is surfaced as an explicit configuration
+ *     error pointing at `HttpClientOptions.webSocketFactory` (e.g. backed by the
+ *     `ws` package, which supports headers) rather than failing silently.
+ *
+ * Tests that replace the factory bypass this entirely.
+ */
+export declare const defaultWebSocketFactory: WebSocketFactory;
+/**
+ * Structural equality for deduping the catch-up/live overlap window. Events
+ * carry no stable id, so a `type` + serialized-`data` comparison is the
+ * pragmatic identity. `timestamp` is excluded because the live frame and the
+ * persisted history record are stamped independently and can differ by a few
+ * milliseconds for the same logical event.
+ */
+export declare function eventsEqual(a: WorkflowEvent, b: WorkflowEvent): boolean;
+/**
+ * Drop the `buffered` live frames that the replayed `history` already covered
+ * (the overlap window), returning the genuinely new frames in order. The dedup
+ * is *consuming*: each history entry can cancel at most one live frame, so two
+ * structurally identical events (e.g. two rapid signals with the same name and
+ * payload) where only one is a true overlap duplicate keep the genuinely new one
+ * instead of both being dropped. Shared by both client transports' catch-up.
+ */
+export declare function dropOverlappingLiveFrames(history: readonly WorkflowEvent[], buffered: readonly WorkflowEvent[]): WorkflowEvent[];
+/** Parse a watch-channel frame into a {@link WorkflowEvent}, or null if malformed. */
+export declare function parseWatchFrame(raw: unknown): WorkflowEvent | null;

package/dist/client/event-stream-transport.js

@@ -0,0 +1,59 @@
+import { detectRuntime } from "../runtime/portable.js";
+export function workflowWatchWebSocketUrl(baseUrl, workflowId) {
+  const trimmed = baseUrl.replace(/\/+$/, ""), path = `/v1/workflows/${encodeURIComponent(workflowId)}/watch`;
+  if (/^https?:/i.test(trimmed))
+    return `${trimmed.replace(/^http:/i, "ws:").replace(/^https:/i, "wss:")}${path}`;
+  const origin = globalThis.location?.origin;
+  if (origin === void 0)
+    return `${trimmed}${path}`;
+  return `${origin.replace(/^http:/i, "ws:").replace(/^https:/i, "wss:")}${trimmed}${path}`;
+}
+export const defaultWebSocketFactory = (url, headers) => {
+  if (typeof WebSocket > "u")
+    throw Error("No global WebSocket is available for live event streaming. Provide HttpClientOptions.webSocketFactory (e.g. backed by the `ws` package) or run on a runtime with a built-in WebSocket (Bun, modern browsers, Node 22+).");
+  const runtime = detectRuntime();
+  if (runtime !== "bun") {
+    if (runtime !== "browser" && Object.keys(headers).length > 0)
+      throw Error("Live event streaming on this runtime cannot send the configured auth headers over WebSocket: the platform WebSocket constructor has no header support. Provide HttpClientOptions.webSocketFactory (e.g. backed by the `ws` package, which supports headers) or authenticate the watch socket with a cookie or query parameter the server accepts.");
+    return new WebSocket(url);
+  }
+  return new WebSocket(url, { headers });
+};
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+export function eventsEqual(a, b) {
+  return a.type === b.type && JSON.stringify(a.data) === JSON.stringify(b.data);
+}
+export function dropOverlappingLiveFrames(history, buffered) {
+  const historyConsumed = Array.from(history, () => !1), fresh = [];
+  for (const live of buffered) {
+    const overlapIndex = history.findIndex((historic, index) => !historyConsumed[index] && eventsEqual(historic, live));
+    if (overlapIndex !== -1) {
+      historyConsumed[overlapIndex] = !0;
+      continue;
+    }
+    fresh.push(live);
+  }
+  return fresh;
+}
+export function parseWatchFrame(raw) {
+  if (typeof raw !== "string")
+    return null;
+  let frame;
+  try {
+    frame = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(frame))
+    return null;
+  const { type } = frame;
+  if (typeof type !== "string")
+    return null;
+  return {
+    type,
+    timestamp: typeof frame.timestamp === "number" ? frame.timestamp : Date.now(),
+    data: isRecord(frame.data) ? frame.data : {}
+  };
+}

package/dist/client/event-stream.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Live workflow-event streaming for {@link HttpClient}.
+ *
+ * The server broadcasts a workflow's lifecycle events over a per-workflow
+ * WebSocket channel at `/v1/workflows/:id/watch` (see the server's
+ * `wireEventBroadcasting`). Each frame is a JSON {@link WorkflowEvent}
+ * (`{ type, timestamp, data }`) — the same shape `getEvents()` returns. This
+ * module opens that channel and exposes the events through two surfaces: a push
+ * callback (`onEvent`) used by {@link HttpHandle.addEventListener} so listeners
+ * fire the moment an event lands instead of on a 2-second poll, and an
+ * {@link AsyncIterable} used by `client.tail(id)` / `handle.tail()`.
+ *
+ * **Catch-up + reconnect.** The watch channel is live-only and a dropped socket
+ * can miss events while disconnected. To close both gaps the subscription
+ * fetches the persisted event history (`getEvents`) on every (re)connect, emits
+ * the events past a confirmed-contiguous history watermark, then drops any live
+ * frame buffered during the fetch that the replayed history already covered (the
+ * overlap window). Delivery is at-least-once: a failed fetch or a shorter
+ * compaction-rebased history array may re-deliver a frame once rather than lose
+ * it. The lone exception is a sequence-less-cursor edge under event-log
+ * compaction — a compacted+regrown log of unchanged length — documented on
+ * `#historyWatermark`; closing it needs a server-exposed event sequence.
+ * Reconnect attempts back off and are capped; the cap is honored even for
+ * open-then-close sockets, since the counter resets only after a catch-up proves
+ * the connection healthy (`#catchUp`).
+ *
+ * **Clean close.** `close()` closes the socket and resolves the iterable.
+ * Terminal workflow events (`completed`, `failed`, `cancelled`, `timed-out`)
+ * auto-close the stream so `for await` consumers terminate when the workflow
+ * finishes.
+ *
+ * @module client/event-stream
+ */
+import type { WorkflowEvent } from '../core/types.ts';
+import { type WebSocketFactory } from './event-stream-transport.ts';
+/** Reason a {@link WorkflowEventSubscription} terminated. */
+export type StreamCloseReason = 'workflow-terminal' | 'client-closed' | 'reconnect-exhausted';
+/** Fetches a workflow's persisted event history for connect/reconnect catch-up. */
+export type EventHistoryFetcher = (workflowId: string) => Promise<WorkflowEvent[]>;
+/** Options for opening a workflow event subscription. */
+export type WorkflowEventStreamOptions = {
+    /** Maximum reconnect attempts after a dropped socket. Default 5. */
+    readonly maxReconnectAttempts?: number;
+    /** Base reconnect backoff in milliseconds. Default 50. */
+    readonly reconnectBackoffMs?: number;
+    /**
+     * Constructor override for the underlying socket. Tests inject a fake here;
+     * production omits it and the global `WebSocket` is used.
+     */
+    readonly webSocketFactory?: WebSocketFactory;
+    /**
+     * Buffer events for async iteration from construction rather than lazily on
+     * first iterator pull. `tail()` sets this so the documented
+     * `await tail.whenConnected(); for await (…)` pattern still sees the connect
+     * catch-up history (which is emitted before the `for await` loop begins).
+     * Callback-only subscribers (`HttpHandle.addEventListener`) leave it off so
+     * the iterator buffer never accumulates a never-drained queue. Default false.
+     */
+    readonly bufferForIteration?: boolean;
+};
+/**
+ * A live workflow-event subscription over the `/watch` WebSocket channel.
+ * Delivers events to a push callback and to a single async iterator, catching
+ * up from persisted history on every (re)connect and transparently reconnecting
+ * when the socket drops.
+ *
+ * The iterator is single-consumer: it drains one shared buffer and parks one
+ * waker, so a second concurrent `for await` over the same subscription would
+ * steal events and clobber the waker. Open a fresh subscription per consumer
+ * instead of iterating one twice.
+ */
+export declare class WorkflowEventSubscription implements AsyncIterable<WorkflowEvent> {
+    #private;
+    constructor(url: string, headers: Record<string, string>, workflowId: string, fetchHistory: EventHistoryFetcher, onEvent: (event: WorkflowEvent) => void, options?: WorkflowEventStreamOptions);
+    /** Why the stream terminated, or `null` while it is still open. */
+    get closeReason(): StreamCloseReason | null;
+    /**
+     * Resolves once the stream is live (socket open and first catch-up done), or
+     * when it terminates — whichever comes first. Await this before driving a
+     * workflow whose events you intend to observe, so no event is missed in the
+     * window before the watch socket connects.
+     */
+    whenConnected(): Promise<void>;
+    /**
+     * Close the subscription cleanly: close the socket and resolve any active
+     * async iteration. Idempotent.
+     */
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent>;
+}

package/dist/client/event-stream.js

@@ -0,0 +1,221 @@
+import { WORKFLOW_TERMINAL_EVENT_TYPES } from "../core/events/workflow-events.js";
+import {
+  defaultWebSocketFactory,
+  dropOverlappingLiveFrames,
+  parseWatchFrame
+} from "./event-stream-transport.js";
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5, DEFAULT_RECONNECT_BACKOFF_MS = 50;
+
+export class WorkflowEventSubscription {
+  #url;
+  #headers;
+  #workflowId;
+  #fetchHistory;
+  #factory;
+  #maxReconnectAttempts;
+  #reconnectBackoffMs;
+  #onEvent;
+  #socket = null;
+  #closed = !1;
+  #historyWatermark = 0;
+  #reconnectAttempts = 0;
+  #reconnectTimer = null;
+  #catchUpInFlight = !1;
+  #pendingLive = [];
+  #connectGeneration = 0;
+  #buffer = [];
+  #waker = null;
+  #iterating = !1;
+  #closeReason = null;
+  #connected = Promise.withResolvers();
+  #connectedSettled = !1;
+  constructor(url, headers, workflowId, fetchHistory, onEvent, options) {
+    this.#url = url;
+    this.#headers = headers;
+    this.#workflowId = workflowId;
+    this.#fetchHistory = fetchHistory;
+    this.#onEvent = onEvent;
+    this.#factory = options?.webSocketFactory ?? defaultWebSocketFactory;
+    this.#maxReconnectAttempts = options?.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    this.#reconnectBackoffMs = options?.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS;
+    this.#iterating = options?.bufferForIteration ?? !1;
+    this.#connect();
+  }
+  get closeReason() {
+    return this.#closeReason;
+  }
+  whenConnected() {
+    return this.#connected.promise;
+  }
+  #markConnected() {
+    if (this.#connectedSettled)
+      return;
+    this.#connectedSettled = !0;
+    this.#connected.resolve();
+  }
+  #connect() {
+    if (this.#closed)
+      return;
+    let socket;
+    try {
+      socket = this.#factory(this.#url, this.#headers);
+    } catch (error) {
+      if (this.#connectGeneration === 0 && this.#reconnectAttempts === 0)
+        throw error;
+      this.#scheduleReconnect();
+      return;
+    }
+    this.#socket = socket;
+    socket.addEventListener("open", () => {
+      if (this.#closed || this.#socket !== socket)
+        return;
+      this.#connectGeneration += 1;
+      this.#catchUp();
+    });
+    socket.addEventListener("message", (event) => {
+      if (this.#socket !== socket)
+        return;
+      const parsed = parseWatchFrame(event.data);
+      if (parsed !== null)
+        this.#deliverLive(parsed);
+    });
+    socket.addEventListener("close", () => {
+      if (this.#socket === socket)
+        this.#handleSocketDrop();
+    });
+    socket.addEventListener("error", () => {});
+  }
+  async#catchUp() {
+    if (this.#catchUpInFlight || this.#closed)
+      return;
+    this.#catchUpInFlight = !0;
+    const generation = this.#connectGeneration;
+    let succeeded = !1;
+    try {
+      succeeded = await this.#reconcileHistory(generation);
+    } finally {
+      this.#catchUpInFlight = !1;
+      if (!this.#closed && generation !== this.#connectGeneration)
+        this.#catchUp();
+      else {
+        if (succeeded && this.#socket !== null)
+          this.#reconnectAttempts = 0;
+        this.#markConnected();
+      }
+    }
+  }
+  async#reconcileHistory(generation) {
+    let history = [], fetchSucceeded = !0;
+    try {
+      history = await this.#fetchHistory(this.#workflowId);
+    } catch {
+      fetchSucceeded = !1;
+      history = [];
+    }
+    if (this.#closed)
+      return !1;
+    if (generation !== this.#connectGeneration)
+      return !1;
+    const newHistory = history.length < this.#historyWatermark ? history : history.slice(this.#historyWatermark);
+    for (const event of newHistory)
+      this.#emit(event);
+    const buffered = this.#pendingLive;
+    this.#pendingLive = [];
+    for (const live of dropOverlappingLiveFrames(newHistory, buffered))
+      this.#emit(live);
+    if (fetchSucceeded)
+      this.#historyWatermark = history.length;
+    return fetchSucceeded;
+  }
+  #deliverLive(event) {
+    if (this.#catchUpInFlight) {
+      this.#pendingLive.push(event);
+      return;
+    }
+    this.#emit(event);
+  }
+  #emit(event) {
+    if (this.#closed)
+      return;
+    try {
+      this.#onEvent(event);
+    } catch {}
+    if (this.#iterating) {
+      this.#buffer.push(event);
+      this.#wake();
+    }
+    if (WORKFLOW_TERMINAL_EVENT_TYPES.has(event.type))
+      this.#terminate("workflow-terminal");
+  }
+  #handleSocketDrop() {
+    this.#socket = null;
+    if (this.#closed)
+      return;
+    this.#scheduleReconnect();
+  }
+  #scheduleReconnect() {
+    if (this.#closed)
+      return;
+    if (this.#reconnectAttempts >= this.#maxReconnectAttempts) {
+      this.#terminate("reconnect-exhausted");
+      return;
+    }
+    this.#reconnectAttempts += 1;
+    const delay = this.#reconnectBackoffMs * this.#reconnectAttempts;
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null;
+      this.#connect();
+    }, delay);
+  }
+  #terminate(reason) {
+    if (this.#closed)
+      return;
+    this.#closed = !0;
+    this.#closeReason = reason;
+    this.#markConnected();
+    if (this.#reconnectTimer !== null) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+    const socket = this.#socket;
+    this.#socket = null;
+    if (socket !== null)
+      try {
+        socket.close();
+      } catch {}
+    this.#wake();
+  }
+  #wake() {
+    const waker = this.#waker;
+    if (waker !== null) {
+      this.#waker = null;
+      waker();
+    }
+  }
+  close() {
+    this.#terminate("client-closed");
+  }
+  [Symbol.asyncIterator]() {
+    this.#iterating = !0;
+    return this.#iterate();
+  }
+  async* #iterate() {
+    try {
+      while (!0) {
+        while (this.#buffer.length > 0)
+          yield this.#buffer.shift();
+        if (this.#closed)
+          return;
+        await this.#waitForEvent();
+      }
+    } finally {
+      this.#iterating = !1;
+      this.close();
+    }
+  }
+  #waitForEvent() {
+    const { promise, resolve } = Promise.withResolvers();
+    this.#waker = resolve;
+    return promise;
+  }
+}

package/dist/client/event-tail.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The client-facing live event tail contract. Both library mode
+ * ({@link LocalClient}, via the in-process engine feed) and server mode
+ * ({@link HttpClient}, via the `/watch` WebSocket channel) return a value
+ * implementing this interface from their `tail()` methods.
+ *
+ * @module client/event-tail
+ */
+import type { WorkflowEvent } from '../core/types.ts';
+/**
+ * A live workflow-event tail. Async-iterate it to consume events as they are
+ * produced; the iteration terminates cleanly when the workflow reaches a
+ * terminal state, the server closes the stream, or {@link WorkflowEventTail.close}
+ * is called.
+ *
+ * The tail is **single-consumer**: both transports drain one shared buffer, so a
+ * second concurrent `for await` over the same tail would steal events from the
+ * first and can leave a consumer hanging. Open a fresh tail per consumer
+ * (`client.tail(id)` / `handle.tail()`) instead of iterating one tail twice.
+ *
+ * @example
+ * ```ts
+ * import { workflow, Engine, MemoryStorage, LocalClient, type WorkflowEventTail } from '@lostgradient/weft';
+ *
+ * await using engine = new Engine({ storage: new MemoryStorage() });
+ * engine.register(workflow({ name: 'ping' }).execute(async function* () { return 'pong'; }));
+ * const client = new LocalClient(engine);
+ * const handle = await client.start('ping', null);
+ * const tail: WorkflowEventTail = client.tail(handle.id);
+ * await tail.whenConnected();
+ * for await (const event of tail) {
+ *   console.log(event.type);
+ * }
+ * ```
+ */
+export interface WorkflowEventTail extends AsyncIterable<WorkflowEvent> {
+    /** Stop the tail and release its resources. Idempotent. */
+    close(): void;
+    /**
+     * Resolves once the tail is live and ready to deliver events (or when it has
+     * terminated). Await this before triggering work whose events you intend to
+     * observe, so nothing is missed in the window before the underlying transport
+     * connects. Both modes resolve only after the connect catch-up has replayed
+     * the workflow's persisted history (server mode after the `/watch` socket's
+     * `getEvents` catch-up; library mode after the in-process `engine.getEvents`
+     * replay), so awaiting it may perform async work and a `for await` started
+     * afterward still sees the replayed history ahead of any live frame.
+     */
+    whenConnected(): Promise<void>;
+}

package/dist/client/handle-delegation.d.ts

@@ -0,0 +1,73 @@
+import type { WeftEventMap } from '../core/events.ts';
+import type { QueryDefinition, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, UpdateDefinition } from '../core/types.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
+import type { ClientHandle, ClientScheduleHandle } from './interface.ts';
+export interface WorkflowHandleDelegationClient {
+    cancel(id: string): Promise<void>;
+    tail(id: string): WorkflowEventTail;
+    signal(id: string, name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    update(id: string, name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    query(id: string, name: string, input?: unknown): Promise<unknown>;
+    getAttributes(id: string): Promise<Record<string, SearchAttributeValue> | null>;
+    setAttributes(id: string, attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    addTags(id: string, ...tags: string[]): Promise<void>;
+    removeTags(id: string, ...tags: string[]): Promise<void>;
+}
+export declare abstract class WorkflowHandleDelegation<TClient extends WorkflowHandleDelegationClient = WorkflowHandleDelegationClient> implements ClientHandle {
+    readonly id: string;
+    protected readonly client: TClient;
+    constructor(id: string, client: TClient);
+    abstract result(): Promise<unknown>;
+    cancel(): Promise<void>;
+    signal(name: SignalDefinition): Promise<void>;
+    signal<TInput>(name: SignalDefinition<TInput>, payload: TInput, options?: SignalDeliveryOptions): Promise<void>;
+    signal(name: string, payload?: unknown, options?: SignalDeliveryOptions): Promise<void>;
+    update<TOutput>(name: UpdateDefinition<void, TOutput>, payload?: void, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update<TInput, TOutput>(name: UpdateDefinition<TInput, TOutput>, payload: TInput, options?: {
+        timeout?: number;
+    }): Promise<TOutput>;
+    update(name: string, payload?: unknown, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    query<TOutput>(name: QueryDefinition<void, TOutput>): Promise<TOutput>;
+    query<TInput, TOutput>(name: QueryDefinition<TInput, TOutput>, input: TInput): Promise<TOutput>;
+    query(name: string, input?: unknown): Promise<unknown>;
+    getAttributes(): Promise<Record<string, SearchAttributeValue> | null>;
+    setAttributes(attributes: Record<string, SearchAttributeValue>): Promise<void>;
+    addTags(...tags: string[]): Promise<void>;
+    removeTags(...tags: string[]): Promise<void>;
+    tail(): WorkflowEventTail;
+    /**
+     * Default readiness: resolved immediately. Transports whose event stream has
+     * connection latency (e.g. the HTTP watch socket) override this to reflect
+     * their own connection state.
+     */
+    whenConnected(): Promise<void>;
+    abstract addEventListener<K extends keyof WeftEventMap>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    abstract addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    abstract removeEventListener<K extends keyof WeftEventMap>(type: K, listener: (event: WeftEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    abstract removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    abstract [Symbol.dispose](): void;
+}
+export interface ScheduleHandleDelegationClient {
+    pauseSchedule(id: string): Promise<void>;
+    resumeSchedule(id: string): Promise<void>;
+    cancelSchedule(id: string): Promise<void>;
+    updateSchedule(id: string, newSpec: string | ScheduleSpec): Promise<void>;
+    getSchedule(id: string): Promise<ScheduleSummary | null>;
+}
+export declare abstract class ScheduleHandleDelegation<TClient extends ScheduleHandleDelegationClient = ScheduleHandleDelegationClient> implements ClientScheduleHandle {
+    readonly id: string;
+    protected readonly client: TClient;
+    constructor(id: string, client: TClient);
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    cancel(): Promise<void>;
+    update(newSpec: string | ScheduleSpec): Promise<void>;
+    describe(): Promise<ScheduleSummary | null>;
+    abstract [Symbol.dispose](): void;
+}

package/dist/client/handle-delegation.js

@@ -0,0 +1,66 @@
+import { messageName } from "../core/types.js";
+
+export class WorkflowHandleDelegation {
+  id;
+  client;
+  constructor(id, client) {
+    this.id = id;
+    this.client = client;
+  }
+  async cancel() {
+    return this.client.cancel(this.id);
+  }
+  async signal(nameOrDefinition, payload, options) {
+    if (options === void 0)
+      return this.client.signal(this.id, messageName(nameOrDefinition), payload);
+    return this.client.signal(this.id, messageName(nameOrDefinition), payload, options);
+  }
+  async update(nameOrDefinition, payload, options) {
+    return this.client.update(this.id, messageName(nameOrDefinition), payload, options);
+  }
+  async query(nameOrDefinition, input) {
+    return this.client.query(this.id, messageName(nameOrDefinition), input);
+  }
+  async getAttributes() {
+    return this.client.getAttributes(this.id);
+  }
+  async setAttributes(attributes) {
+    return this.client.setAttributes(this.id, attributes);
+  }
+  async addTags(...tags) {
+    return this.client.addTags(this.id, ...tags);
+  }
+  async removeTags(...tags) {
+    return this.client.removeTags(this.id, ...tags);
+  }
+  tail() {
+    return this.client.tail(this.id);
+  }
+  whenConnected() {
+    return Promise.resolve();
+  }
+}
+
+export class ScheduleHandleDelegation {
+  id;
+  client;
+  constructor(id, client) {
+    this.id = id;
+    this.client = client;
+  }
+  async pause() {
+    return this.client.pauseSchedule(this.id);
+  }
+  async resume() {
+    return this.client.resumeSchedule(this.id);
+  }
+  async cancel() {
+    return this.client.cancelSchedule(this.id);
+  }
+  async update(newSpec) {
+    return this.client.updateSchedule(this.id, newSpec);
+  }
+  async describe() {
+    return this.client.getSchedule(this.id);
+  }
+}