@lostgradient/weft 0.5.0 → 0.7.0

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

@@ -0,0 +1,58 @@
+import type { WebSocketFactory } from './event-stream-transport.ts';
+/**
+ * Transport preference for live workflow event subscriptions opened by
+ * {@link HttpClient}. `auto` keeps the WebSocket watch channel as the default
+ * and falls back to fetch-based SSE only when WebSocket construction cannot
+ * carry the required authentication headers.
+ *
+ * @example
+ * ```ts
+ * import { type WorkflowEventTransport } from '@lostgradient/weft';
+ *
+ * const transport: WorkflowEventTransport = 'sse';
+ * void transport;
+ * ```
+ */
+export type WorkflowEventTransport = 'auto' | 'websocket' | 'sse';
+/**
+ * Options for opening a live workflow event subscription from an
+ * {@link HttpClient} or {@link HttpHandle}. These options apply to
+ * `client.tail(id)`, `handle.tail()`, and handle event listeners.
+ *
+ * @example
+ * ```ts
+ * import { HttpClient, type WorkflowEventStreamOptions } from '@lostgradient/weft';
+ *
+ * const eventStreamOptions = {
+ *   eventTransport: 'sse',
+ * } satisfies WorkflowEventStreamOptions;
+ *
+ * const client = new HttpClient({
+ *   baseUrl: 'http://localhost:7233',
+ *   eventTransport: eventStreamOptions.eventTransport,
+ * });
+ * void client;
+ * ```
+ */
+export type WorkflowEventStreamOptions = {
+    /** Live event transport selection. Default `auto`. */
+    readonly eventTransport?: WorkflowEventTransport;
+    /** 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;
+};

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

@@ -2,27 +2,31 @@
  * 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()`.
+ * WebSocket channel at `/v1/workflows/:id/watch`, with fetch-based SSE at
+ * `/v1/workflows/:id/events/sse` for authenticated runtimes that cannot carry
+ * headers through WebSocket construction. Each delivered frame becomes a JSON
+ * {@link WorkflowEvent} (`{ type, timestamp, data }`) — the same shape
+ * `getEvents()` returns. This module opens the selected 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`).
+ * **Catch-up + reconnect.** The WebSocket watch channel is live-only and a
+ * dropped socket can miss events while disconnected. To close both gaps the
+ * WebSocket 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). SSE uses the server's
+ * cursor-backed replay feed and reconnects with `Last-Event-ID`. 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 WebSocket 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; for WebSocket 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`)
@@ -32,32 +36,11 @@
  * @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';
+import type { WorkflowEventStreamOptions } from './event-stream-options.ts';
+import { type StreamCloseReason } from './event-tail-lifecycle.ts';
+export type { StreamCloseReason } from './event-tail-lifecycle.ts';
 /** 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

package/dist/client/event-stream.js

@@ -4,6 +4,7 @@ import {
   dropOverlappingLiveFrames,
   parseWatchFrame
 } from "./event-stream-transport.js";
+import { WorkflowEventTailLifecycle } from "./event-tail-lifecycle.js";
 const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5, DEFAULT_RECONNECT_BACKOFF_MS = 50;
 
 export class WorkflowEventSubscription {
@@ -15,18 +16,14 @@ export class WorkflowEventSubscription {
   #maxReconnectAttempts;
   #reconnectBackoffMs;
   #onEvent;
+  #lifecycle;
   #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) {
@@ -38,11 +35,14 @@ export class WorkflowEventSubscription {
     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.#lifecycle = new WorkflowEventTailLifecycle({
+      bufferForIteration: options?.bufferForIteration ?? !1,
+      onClose: (reason) => this.#onLifecycleClose(reason)
+    });
     this.#connect();
   }
   get closeReason() {
-    return this.#closeReason;
+    return this.#lifecycle.closeReason;
   }
   whenConnected() {
     return this.#connected.promise;
@@ -54,7 +54,7 @@ export class WorkflowEventSubscription {
     this.#connected.resolve();
   }
   #connect() {
-    if (this.#closed)
+    if (this.#lifecycle.closed)
       return;
     let socket;
     try {
@@ -67,7 +67,7 @@ export class WorkflowEventSubscription {
     }
     this.#socket = socket;
     socket.addEventListener("open", () => {
-      if (this.#closed || this.#socket !== socket)
+      if (this.#lifecycle.closed || this.#socket !== socket)
         return;
       this.#connectGeneration += 1;
       this.#catchUp();
@@ -86,7 +86,7 @@ export class WorkflowEventSubscription {
     socket.addEventListener("error", () => {});
   }
   async#catchUp() {
-    if (this.#catchUpInFlight || this.#closed)
+    if (this.#catchUpInFlight || this.#lifecycle.closed)
       return;
     this.#catchUpInFlight = !0;
     const generation = this.#connectGeneration;
@@ -95,7 +95,7 @@ export class WorkflowEventSubscription {
       succeeded = await this.#reconcileHistory(generation);
     } finally {
       this.#catchUpInFlight = !1;
-      if (!this.#closed && generation !== this.#connectGeneration)
+      if (!this.#lifecycle.closed && generation !== this.#connectGeneration)
         this.#catchUp();
       else {
         if (succeeded && this.#socket !== null)
@@ -112,7 +112,7 @@ export class WorkflowEventSubscription {
       fetchSucceeded = !1;
       history = [];
     }
-    if (this.#closed)
+    if (this.#lifecycle.closed)
       return !1;
     if (generation !== this.#connectGeneration)
       return !1;
@@ -135,26 +135,20 @@ export class WorkflowEventSubscription {
     this.#emit(event);
   }
   #emit(event) {
-    if (this.#closed)
+    if (this.#lifecycle.closed)
       return;
-    try {
-      this.#onEvent(event);
-    } catch {}
-    if (this.#iterating) {
-      this.#buffer.push(event);
-      this.#wake();
-    }
+    this.#lifecycle.emit(event, this.#onEvent);
     if (WORKFLOW_TERMINAL_EVENT_TYPES.has(event.type))
       this.#terminate("workflow-terminal");
   }
   #handleSocketDrop() {
     this.#socket = null;
-    if (this.#closed)
+    if (this.#lifecycle.closed)
       return;
     this.#scheduleReconnect();
   }
   #scheduleReconnect() {
-    if (this.#closed)
+    if (this.#lifecycle.closed)
       return;
     if (this.#reconnectAttempts >= this.#maxReconnectAttempts) {
       this.#terminate("reconnect-exhausted");
@@ -168,10 +162,9 @@ export class WorkflowEventSubscription {
     }, delay);
   }
   #terminate(reason) {
-    if (this.#closed)
-      return;
-    this.#closed = !0;
-    this.#closeReason = reason;
+    this.#lifecycle.terminate(reason);
+  }
+  #onLifecycleClose(_reason) {
     this.#markConnected();
     if (this.#reconnectTimer !== null) {
       clearTimeout(this.#reconnectTimer);
@@ -183,39 +176,11 @@ export class WorkflowEventSubscription {
       try {
         socket.close();
       } catch {}
-    this.#wake();
-  }
-  #wake() {
-    const waker = this.#waker;
-    if (waker !== null) {
-      this.#waker = null;
-      waker();
-    }
   }
   close() {
-    this.#terminate("client-closed");
+    this.#lifecycle.close();
   }
   [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;
+    return this.#lifecycle[Symbol.asyncIterator]();
   }
 }

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

@@ -0,0 +1,21 @@
+import type { WorkflowEvent } from '../core/types.ts';
+/** Reason a workflow event tail terminated. */
+export type StreamCloseReason = 'workflow-terminal' | 'client-closed' | 'reconnect-exhausted' | 'server-error';
+export type WorkflowEventTailLifecycleOptions = {
+    readonly bufferForIteration?: boolean;
+    readonly onClose: (reason: StreamCloseReason) => void;
+};
+/**
+ * Shared async-iterator lifecycle for client event tails. Transports own
+ * connection mechanics; this owns buffering, close state, and wake-up handling.
+ */
+export declare class WorkflowEventTailLifecycle implements AsyncIterable<WorkflowEvent> {
+    #private;
+    constructor(options: WorkflowEventTailLifecycleOptions);
+    get closed(): boolean;
+    get closeReason(): StreamCloseReason | null;
+    emit(event: WorkflowEvent, onEvent: (event: WorkflowEvent) => void): boolean;
+    terminate(reason: StreamCloseReason): void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent>;
+}

package/dist/client/event-tail-lifecycle.js

@@ -0,0 +1,71 @@
+export class WorkflowEventTailLifecycle {
+  #buffer = [];
+  #onClose;
+  #closeReason = null;
+  #closed = !1;
+  #iterating = !1;
+  #waker = null;
+  constructor(options) {
+    this.#onClose = options.onClose;
+    this.#iterating = options.bufferForIteration ?? !1;
+  }
+  get closed() {
+    return this.#closed;
+  }
+  get closeReason() {
+    return this.#closeReason;
+  }
+  emit(event, onEvent) {
+    if (this.#closed)
+      return !1;
+    try {
+      onEvent(event);
+    } catch {}
+    if (this.#iterating) {
+      this.#buffer.push(event);
+      this.#wake();
+    }
+    return !0;
+  }
+  terminate(reason) {
+    if (this.#closed)
+      return;
+    this.#closed = !0;
+    this.#closeReason = reason;
+    this.#onClose(reason);
+    this.#wake();
+  }
+  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;
+  }
+  #wake() {
+    const waker = this.#waker;
+    if (waker !== null) {
+      this.#waker = null;
+      waker();
+    }
+  }
+}

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

@@ -44,7 +44,9 @@ export interface WorkflowEventTail extends AsyncIterable<WorkflowEvent> {
      * 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.
+     * afterward still sees the replayed history ahead of any live frame. Server
+     * mode uses the `/watch` socket's `getEvents` catch-up for WebSocket tails
+     * and the replay-complete `ping` frame for SSE tails.
      */
     whenConnected(): Promise<void>;
 }

package/dist/client/http-client.d.ts

@@ -1,10 +1,9 @@
 import { type CatalogOperationName, type CatalogOperationTypes, type WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { StoredStreamChunk } from '../core/context.ts';
 import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
-import { type WorkflowEventSubscription } from './event-stream.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import { type HttpClientOptions } from './http-request.ts';
-import type { ClientHandle, ClientScheduleHandle, ClientStartOptions, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
+import type { ClientHandle, ClientScheduleHandle, ClientStartOptions, ClientStartOrSignalOptions, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
 /**
  * Remote Weft client backed by HTTP requests.
@@ -61,8 +60,8 @@ export declare class HttpClient implements WeftClient {
     call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: ClientStartOptions): Promise<ClientHandle>;
-    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
-    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Promise<ClientHandle>;
     schedule<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     get(id: string): Promise<WorkflowState | null>;
@@ -110,7 +109,7 @@ export declare class HttpClient implements WeftClient {
      * path; {@link tail} sets it so the connect catch-up is buffered for the
      * async iterator instead of dropped.
      */
-    openEventSubscription(id: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventSubscription;
+    openEventSubscription(id: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventTail;
     tail(id: string): WorkflowEventTail;
     getTimeline(id: string): Promise<WorkflowTimelineEntry[]>;
     replayTo(id: string, step: number): Promise<WorkflowReplay | null>;

package/dist/client/http-client.js

@@ -62,7 +62,10 @@ export class HttpClient {
       complete: (token, result) => completeAsyncActivityRequest(this, token, result),
       completeExceptionally: (token, error) => failAsyncActivityRequest(this, token, error)
     };
-    this.#streamOptions = options.webSocketFactory === void 0 ? {} : { webSocketFactory: options.webSocketFactory };
+    this.#streamOptions = {
+      ...options.eventTransport === void 0 ? {} : { eventTransport: options.eventTransport },
+      ...options.webSocketFactory === void 0 ? {} : { webSocketFactory: options.webSocketFactory }
+    };
   }
   call(name, input) {
     return this.operations[name](input);

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

@@ -3,11 +3,10 @@ import { WorkflowHandleDelegation } from './handle-delegation.ts';
 import type { HttpClient } from './http-client.ts';
 /**
  * Server-mode workflow handle. Lifecycle events are delivered push-based over
- * the server's per-workflow `/v1/workflows/:id/watch` WebSocket channel rather
- * than by polling `getEvents()` on a timer — listeners fire the moment an event
- * lands on the server. Each delivered event is re-dispatched as a `CustomEvent`
- * whose `detail` is the event's `data`, matching the long-standing handle
- * contract.
+ * the server's per-workflow WebSocket or SSE event stream rather than by
+ * polling `getEvents()` on a timer — listeners fire the moment an event lands
+ * on the server. Each delivered event is re-dispatched as a `CustomEvent` whose
+ * `detail` is the event's `data`, matching the long-standing handle contract.
  */
 export declare class HttpHandle extends WorkflowHandleDelegation<HttpClient> {
     #private;

package/dist/client/http-request.d.ts

@@ -1,6 +1,7 @@
 import { type FaultCode } from '../core/fault-code.ts';
 import type { FailureCategory } from '../core/types/identity.ts';
 import { WeftError, type WeftErrorCode } from '../core/weft-error.ts';
+import type { WorkflowEventTransport } from './event-stream-options.ts';
 import type { WebSocketFactory } from './event-stream-transport.ts';
 /**
  * Configuration for the HTTP client.
@@ -32,6 +33,12 @@ export interface HttpClientOptions {
     token?: string;
     /** Optional headers to include on every request (e.g. auth tokens). */
     headers?: Record<string, string>;
+    /**
+     * Live workflow-event transport. `auto` prefers WebSocket and falls back to
+     * fetch-based SSE when the initial WebSocket constructor cannot carry the
+     * configured headers. Defaults to `auto`.
+     */
+    eventTransport?: WorkflowEventTransport;
     /**
      * Override the WebSocket constructor used for live event streaming
      * (`tail()` / push-based `handle.addEventListener`). Production omits this and

package/dist/client/index.d.ts

@@ -7,9 +7,10 @@
  *
  * @module client/index
  */
+export type { WorkflowEventStreamOptions, WorkflowEventTransport } from './event-stream-options.ts';
 export type { WorkflowEventTail } from './event-tail.ts';
 export { HttpClient } from './http-client.ts';
 export { HttpClientError } from './http-request.ts';
 export type { HttpClientOptions } from './http-request.ts';
-export type { ClientHandle, ClientScheduleHandle, ClientStartOptions, StartOrSignalOutcome, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
+export type { ClientHandle, ClientScheduleHandle, ClientStartOptions, ClientStartOrSignalOptions, StartOrSignalOutcome, UpdateResult, WeftClient, WeftClientActivity, } from './interface.ts';
 export type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';

package/dist/client/interface.d.ts

@@ -9,7 +9,7 @@ import type { CatalogOperationName, CatalogOperationTypes, WeftClient as Catalog
 import type { StoredStreamChunk } from '../core/context.ts';
 import type { StartOrSignalOutcome as EngineStartOrSignalOutcome } from '../core/engine/handles.ts';
 import type { TypedEventTarget, WeftEventMap } from '../core/events.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
 /**
@@ -32,6 +32,19 @@ export type ClientStartOptions = Omit<StartOptions, 'defer' | 'services'> & {
     readonly defer?: never;
     readonly services?: never;
 };
+/**
+ * Remote-capable start-or-signal options, including terminal restart policy.
+ * @example
+ * ```ts
+ * import type { ClientStartOrSignalOptions } from '@lostgradient/weft/client';
+ * const options: ClientStartOrSignalOptions = {
+ *   id: 'github:installations:42:sync',
+ *   onTerminalConflict: 'start-new',
+ * };
+ * void options;
+ * ```
+ */
+export type ClientStartOrSignalOptions = ClientStartOptions & Pick<StartOrSignalOptions, 'onTerminalConflict'>;
 /**
  * Which atomic path a {@link WeftClient.startOrSignal} call took, returned
  * alongside the {@link ClientHandle}. `'started'` when the call created the
@@ -260,7 +273,9 @@ export interface WeftClient {
      * Atomically start a workflow or signal it if it already exists
      * (signal-with-start). An absent target is created and delivered the signal in
      * one batch; a non-terminal target (running, pending, or suspended) is
-     * signalled; a terminal target is rejected as a conflict.
+     * signalled; a terminal target is rejected as a conflict unless
+     * `options.onTerminalConflict: 'start-new'` is supplied with an explicit
+     * workflow id and deterministic `signal.signalId`.
      *
      * The rejection shape is transport-dependent: `LocalClient` throws the typed
      * `StartOrSignalConflictError` (and `IdempotencyKeyPurgedError` for a spent
@@ -276,10 +291,11 @@ export interface WeftClient {
      * atomic start-with-one-signal that does NOT converge concurrent callers (each
      * gets its own run). Supply exactly one of `signal.signalId` or
      * `options.idempotencyKey`; `options.id` and `options.idempotencyKey` are
-     * mutually exclusive.
+     * mutually exclusive. `options.onTerminalConflict: 'start-new'` is also
+     * mutually exclusive with `options.idempotencyKey`.
      */
-    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
-    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Promise<ClientHandle>;
     /**
      * Register a recurring schedule (cron string or interval spec) and return a
      * handle to it.
@@ -368,8 +384,8 @@ export interface WeftClient {
     /**
      * Open a live, push-based tail of a workflow's events. Async-iterate the
      * returned {@link WorkflowEventTail} to consume events as they happen. In
-     * server mode this rides the per-workflow `/v1/workflows/:id/watch` WebSocket
-     * channel (replacing the old 2-second poll); in library mode it bridges the
+     * server mode this rides the configured per-workflow WebSocket or SSE event
+     * stream (replacing the old 2-second poll); in library mode it bridges the
      * engine's event stream directly. Both transports deliver the same
      * {@link WorkflowEvent} records and terminate cleanly on completion or close.
      */

package/dist/client/local-handles.d.ts

@@ -18,5 +18,7 @@ export declare class LocalHandle extends WorkflowHandleDelegation<LocalClient> {
     [Symbol.dispose](): void;
 }
 export declare class LocalScheduleHandle extends ScheduleHandleDelegation<LocalClient> {
+    #private;
+    constructor(id: string, client: LocalClient);
     [Symbol.dispose](): void;
 }

package/dist/client/local-handles.js

@@ -19,5 +19,14 @@ export class LocalHandle extends WorkflowHandleDelegation {
 }
 
 export class LocalScheduleHandle extends ScheduleHandleDelegation {
-  [Symbol.dispose]() {}
+  #disposed;
+  constructor(id, client) {
+    super(id, client);
+    this.#disposed = !1;
+  }
+  [Symbol.dispose]() {
+    if (this.#disposed)
+      return;
+    this.#disposed = !0;
+  }
 }

package/dist/client/local.d.ts

@@ -9,7 +9,7 @@
  */
 import { type CatalogOperationName, type CatalogOperationTypes, type WeftClient as CatalogOperations } from '../cli/generated/operation-client.generated.ts';
 import type { Engine } from '../core/engine.ts';
-import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, DefaultActivityTypes, DefaultWorkflowRegistry, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
+import type { AttributeFilterKey, BulkCancelResult, BulkDeleteResult, BulkRetryFailedResult, BulkSignalResult, BulkTagResult, CoordinatedUpdateResult, DefaultActivityTypes, DefaultWorkflowRegistry, ForkOptions, ListFilter, PaginatedResult, PurgeResult, QueryDefinition, RetentionOverview, ReviewListEntry, ReviewListFilter, ScheduleFilter, ScheduleOptions, ScheduleSpec, ScheduleSummary, SearchAttributeValue, SignalDefinition, SignalDeliveryOptions, StartOptions, StartOrSignalOptions, StartOrSignalSignal, SubmitReviewOptions, TypedListFilter, UpdateDefinition, WorkflowEvent, WorkflowInput, WorkflowOutput, WorkflowRegistry, WorkflowReplay, WorkflowState, WorkflowSummary, WorkflowTimelineEntry } from '../core/types.ts';
 import type { WorkflowEventTail } from './event-tail.ts';
 import type { ClientHandle, ClientScheduleHandle, UpdateResult, WeftClient, WeftClientActivity } from './interface.ts';
 import type { KnownWorkflowName, UnknownNameWhenRegistryEmpty } from './workflow-name-typing.ts';
@@ -57,8 +57,8 @@ export declare class LocalClient<TWorkflows extends object = DefaultWorkflowRegi
     call<Name extends CatalogOperationName>(name: Name, input: CatalogOperationTypes[Name]['input']): Promise<CatalogOperationTypes[Name]['output']>;
     start<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
     start<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, options?: StartOptions): Promise<ClientHandle>;
-    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
-    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOptions): Promise<ClientHandle>;
+    startOrSignal<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, signal: StartOrSignalSignal, options?: StartOrSignalOptions): Promise<ClientHandle<WorkflowOutput<WorkflowRegistry, TName>>>;
+    startOrSignal<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, signal: StartOrSignalSignal, options?: StartOrSignalOptions): Promise<ClientHandle>;
     schedule<TName extends KnownWorkflowName>(type: TName, input: WorkflowInput<WorkflowRegistry, TName>, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     schedule<TName extends string>(type: UnknownNameWhenRegistryEmpty<TName>, input: unknown, spec: string | ScheduleSpec, options?: ScheduleOptions): Promise<ClientScheduleHandle>;
     get(id: string): Promise<WorkflowState | null>;