@lostgradient/weft 0.6.0 → 0.8.0

package/dist/server/operations/fleet-events-sse.d.ts

@@ -0,0 +1,11 @@
+import type { FleetEventEnvelope } from '../fleet-event-feed.ts';
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+type FleetEventsSseOutput = AsyncIterable<FleetEventEnvelope>;
+export declare const fleetEventsSseOperation: import("../operation-catalog.ts").OperationDefinition<{
+    workflowId?: string | undefined;
+    kind?: "human-review:requested" | "human-review:completed" | "alert:fired" | "alert:resolved" | "activity:started" | "activity:completed" | "activity:async-pending" | "activity:failed" | "task:dead-lettered" | "attributes:changed" | "schedule:fired" | "schedule:missed-fire" | "signal:received" | "signal:delivered" | "checkpoint:size-warning" | "development:warning" | "cleanup:warning" | "storage:size-reported" | "worker:connected" | "worker:disconnected" | "constraint:violated" | "update:received" | "update:completed" | "workflow:started" | "workflow:completed" | "workflow:failed" | "workflow:cancelled" | "workflow:timed-out" | "workflow:resumed" | "workflow:suspended" | "workflow:teardown" | undefined;
+    fromCursor?: string | undefined;
+    lastEventId?: string | undefined;
+}, FleetEventsSseOutput, FleetEventEnvelope>;
+export declare const fleetEventsSseRestBinding: UnknownRestBinding;
+export {};

package/dist/server/operations/fleet-events-sse.js

@@ -0,0 +1,164 @@
+import { z } from "zod";
+import { defineOperation } from "../operation-registry.js";
+import { EVENTS_READ_EVENT_TYPES } from "../runtime/client-visible-events.js";
+import {
+  decodeCursor
+} from "../workflow-event-feed.js";
+import { invalidParamsFault } from "./operation-helpers.js";
+import {
+  createEventEnvelopeSSEStream,
+  readServerSentEventsCursor,
+  requireServerSentEventsAccept,
+  shapeServerSentEventsFault,
+  SSE_RESPONSE_HEADERS
+} from "./sse-stream.js";
+const INITIAL_CURSOR = "-1", MAX_FLEET_SSE_REPLAY_EVENTS = 1000, cursorSchema = z.string().refine((cursor) => decodeCursor(cursor) !== null, {
+  message: "Invalid cursor"
+}), fleetEventKindSchema = z.enum(EVENTS_READ_EVENT_TYPES), fleetEventsSseInputSchema = z.object({
+  workflowId: z.string().min(1).optional(),
+  kind: fleetEventKindSchema.optional(),
+  fromCursor: cursorSchema.optional(),
+  lastEventId: cursorSchema.optional()
+}), fleetEventsSseOutputSchema = z.custom(isAsyncIterable, "Expected async iterable fleet event stream"), fleetEventEnvelopeSchema = z.object({
+  kind: z.string(),
+  workflowId: z.string().optional(),
+  sequence: z.number(),
+  cursor: z.string(),
+  emittedAtMs: z.number(),
+  payload: z.unknown()
+});
+export const fleetEventsSseOperation = defineOperation({
+  name: "weft.events.sse",
+  mcpExposable: !1,
+  kind: "stream",
+  summary: "Stream fleet events as Server-Sent Events",
+  description: "Streams the server-level event feed across workflows. Optional filters narrow delivery by workflow id or event kind after the single fleet cursor has been applied. The stream emits `ping` keepalives while idle.",
+  destructive: !1,
+  tags: ["Events"],
+  inputSchema: fleetEventsSseInputSchema,
+  outputSchema: fleetEventsSseOutputSchema,
+  eventSchema: fleetEventEnvelopeSchema,
+  access: {
+    kind: "scoped",
+    scopes: { kind: "anyOf", scopes: ["events:read"] }
+  },
+  producibleFaults: ["InvalidParams", "UnsupportedTransport"],
+  discoverable: !0,
+  transports: { http: !0, jsonRpcHttp: !1, jsonRpcWebSocket: !1, jsonRpcStdio: !1 },
+  unknownKeyPolicy: { http: "strip", jsonRpc: "reject" },
+  invoke: async ({ input, engine }) => {
+    return createFleetEventsIterable(input, fleetEventStreamOperationContext(engine));
+  }
+});
+function fleetEventStreamOperationContext(engine) {
+  if (typeof engine !== "object" || engine === null)
+    return {};
+  return engine;
+}
+function unsupportedEventStreamContextFault(message) {
+  return {
+    code: "UnsupportedTransport",
+    message,
+    data: { transport: "http-rest", supported: ["http-rest"] }
+  };
+}
+function isAsyncIterable(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  return typeof value[Symbol.asyncIterator] === "function";
+}
+function isClosableFleetEventsIterable(value) {
+  return "close" in value && typeof value.close === "function";
+}
+function isReplayAwareFleetEventsIterable(value) {
+  return isClosableFleetEventsIterable(value) && "replayComplete" in value && value.replayComplete instanceof Promise;
+}
+function matchesFleetEventFilter(envelope, input) {
+  if (input.workflowId !== void 0 && envelope.workflowId !== input.workflowId)
+    return !1;
+  if (input.kind !== void 0 && envelope.kind !== input.kind)
+    return !1;
+  return !0;
+}
+function createFleetEventsIterable(input, context) {
+  const feed = context.fleetEventFeed;
+  if (feed === void 0)
+    throw unsupportedEventStreamContextFault("fleet event SSE requires a fleet event feed");
+  const controller = new AbortController, replayComplete = Promise.withResolvers();
+  let closed = !1;
+  const close = async () => {
+    if (closed)
+      return;
+    closed = !0;
+    controller.abort();
+  }, subscribeOptions = {
+    fromCursor: input.lastEventId ?? input.fromCursor ?? INITIAL_CURSOR,
+    signal: controller.signal,
+    replayLimit: MAX_FLEET_SSE_REPLAY_EVENTS,
+    filterEnvelope: (envelope) => matchesFleetEventFilter(envelope, input),
+    onReplayComplete: () => replayComplete.resolve(),
+    createReplayLimitError: (count, limit) => invalidParamsFault(`Fleet event replay window is ${count} matching events; maximum is ${limit}. Supply a more recent fromCursor.`)
+  };
+  let source;
+  try {
+    source = feed.subscribe(subscribeOptions);
+  } catch (error) {
+    close();
+    throw error;
+  }
+  return {
+    async* [Symbol.asyncIterator]() {
+      try {
+        for await (const envelope of source)
+          yield envelope;
+      } finally {
+        await close();
+      }
+    },
+    replayComplete: replayComplete.promise,
+    close
+  };
+}
+function shapeFleetEventsSseSuccess(output, request) {
+  const close = isClosableFleetEventsIterable(output) ? () => output.close() : async () => {
+    return;
+  };
+  return new Response(createEventEnvelopeSSEStream({
+    iterable: output,
+    close,
+    ...isReplayAwareFleetEventsIterable(output) ? { ready: output.replayComplete } : {},
+    signal: request.signal
+  }), {
+    status: 200,
+    headers: SSE_RESPONSE_HEADERS
+  });
+}
+function shapeFleetEventsSseFault(fault) {
+  return shapeServerSentEventsFault(fault);
+}
+export const fleetEventsSseRestBinding = {
+  method: "GET",
+  path: "/v1/events/sse",
+  pathParamNames: [],
+  operationName: "weft.events.sse",
+  transportKind: "sse",
+  inputSources: {
+    workflowId: { kind: "query", queryParam: "workflowId" },
+    kind: { kind: "query", queryParam: "kind" },
+    fromCursor: { kind: "query", queryParam: "fromCursor" },
+    lastEventId: { kind: "header", headerName: "Last-Event-ID" }
+  },
+  extractInput: async (request) => {
+    requireServerSentEventsAccept(request);
+    const url = new URL(request.url), workflowId = url.searchParams.get("workflowId") ?? void 0, kind = url.searchParams.get("kind") ?? void 0, lastEventId = readServerSentEventsCursor(request.headers.get("Last-Event-ID")), fromCursor = lastEventId === void 0 ? readServerSentEventsCursor(url.searchParams.get("fromCursor")) : void 0;
+    return {
+      ...workflowId === void 0 ? {} : { workflowId },
+      ...kind === void 0 ? {} : { kind },
+      ...fromCursor === void 0 ? {} : { fromCursor },
+      ...lastEventId === void 0 ? {} : { lastEventId }
+    };
+  },
+  success: { kind: "streaming", mediaType: "text/event-stream" },
+  shapeSuccess: shapeFleetEventsSseSuccess,
+  shapeFault: shapeFleetEventsSseFault
+};

package/dist/server/operations/sse-stream.d.ts

@@ -1,4 +1,46 @@
 import type { StoredStreamChunk } from '../../core/context.ts';
+import type { OperationFault } from '../operation-fault.ts';
+import { type Cursor } from '../workflow-event-feed.ts';
+export type ServerSentEventTimerScheduler = (callback: () => void, intervalMs: number) => () => void;
+export type ServerSentEventHeartbeatOptions = {
+    readonly intervalMs: number;
+    readonly schedule?: ServerSentEventTimerScheduler;
+    readonly now?: () => number;
+};
+type ServerSentEventEnvelope = {
+    readonly kind: string;
+    readonly cursor: string;
+    readonly emittedAtMs: number;
+};
+type EventEnvelopeSSEStreamOptions<TEnvelope extends ServerSentEventEnvelope> = {
+    readonly iterable: AsyncIterable<TEnvelope>;
+    readonly close: () => Promise<void>;
+    readonly ready?: Promise<void>;
+    readonly heartbeat?: ServerSentEventHeartbeatOptions;
+    readonly signal?: AbortSignal;
+};
+export declare const SSE_ACCEPT_REQUIRED_MESSAGE = "Accept header must include text/event-stream";
+export declare function acceptsServerSentEvents(acceptHeader: string | null): boolean;
+export declare function requireServerSentEventsAccept(request: Request): void;
+/**
+ * Validate an SSE reconnect cursor taken from a `Last-Event-ID` header or
+ * `fromCursor` query parameter. Returns `undefined` for an absent value and
+ * throws an `InvalidParams` fault for a malformed one. Shared by every SSE
+ * binding so cursor validation stays defined in exactly one place.
+ */
+export declare function readServerSentEventsCursor(value: string | null): Cursor | undefined;
+export declare function shapeServerSentEventsFault(fault: OperationFault): Response;
+/** Format a single Server-Sent Events message. */
+export declare function formatServerSentEvent(event: {
+    readonly id?: string;
+    readonly event?: string;
+    readonly data: string;
+}): string;
+/**
+ * Convert a replay-plus-live event envelope iterable into an SSE byte stream.
+ * Event envelopes advance the client cursor via `id`; heartbeat pings do not.
+ */
+export declare function createEventEnvelopeSSEStream<TEnvelope extends ServerSentEventEnvelope>(options: EventEnvelopeSSEStreamOptions<TEnvelope>): ReadableStream<Uint8Array>;
 /**
  * Wrap a list of stored stream chunks as a Server-Sent Events stream. Each
  * chunk gets emitted as a `token` event keyed by `chunk.sequence`; chunks
@@ -11,3 +53,4 @@ import type { StoredStreamChunk } from '../../core/context.ts';
 export declare function createStoredChunkSSEStream(chunks: ReadonlyArray<StoredStreamChunk>, mapChunkToText: (chunk: StoredStreamChunk) => string | null): ReadableStream<Uint8Array>;
 /** Standard headers for an SSE response. */
 export declare const SSE_RESPONSE_HEADERS: Readonly<Record<string, string>>;
+export {};

package/dist/server/operations/sse-stream.js

@@ -1,5 +1,39 @@
-const textEncoder = new TextEncoder;
-function formatSSE(event) {
+import { decodeCursor } from "../workflow-event-feed.js";
+import {
+  invalidParamsFault,
+  isOperationFault,
+  jsonErrorResponse,
+  shapeRestFault
+} from "./operation-helpers.js";
+const textEncoder = new TextEncoder, DEFAULT_SSE_HEARTBEAT_INTERVAL_MS = 15000;
+export const SSE_ACCEPT_REQUIRED_MESSAGE = "Accept header must include text/event-stream";
+export function acceptsServerSentEvents(acceptHeader) {
+  if (acceptHeader === null)
+    return !1;
+  for (const entry of acceptHeader.split(",")) {
+    const mediaType = entry.split(";", 1)[0]?.trim().toLowerCase();
+    if (mediaType === "text/event-stream" || mediaType === "text/*" || mediaType === "*/*")
+      return !0;
+  }
+  return !1;
+}
+export function requireServerSentEventsAccept(request) {
+  if (!acceptsServerSentEvents(request.headers.get("Accept")))
+    throw invalidParamsFault(SSE_ACCEPT_REQUIRED_MESSAGE);
+}
+export function readServerSentEventsCursor(value) {
+  if (value === null)
+    return;
+  if (decodeCursor(value) === null)
+    throw invalidParamsFault("Invalid cursor");
+  return value;
+}
+export function shapeServerSentEventsFault(fault) {
+  if (fault.code === "InvalidParams" && fault.message === SSE_ACCEPT_REQUIRED_MESSAGE)
+    return jsonErrorResponse(fault.message, 406);
+  return shapeRestFault(fault);
+}
+export function formatServerSentEvent(event) {
   const lines = [];
   if (event.id !== void 0)
     lines.push(`id: ${event.id}`);
@@ -14,6 +48,116 @@ function formatSSE(event) {
 `) + `
 `;
 }
+function scheduleInterval(callback, intervalMs) {
+  const timer = setInterval(callback, intervalMs);
+  return () => {
+    clearInterval(timer);
+  };
+}
+function encodeFrame(frame) {
+  return textEncoder.encode(formatServerSentEvent(frame));
+}
+function sanitizedErrorFrame(error) {
+  if (isOperationFault(error) && error.code !== "EngineFailure")
+    return {
+      event: "error",
+      data: JSON.stringify({
+        code: error.code,
+        message: error.message,
+        data: error.data
+      })
+    };
+  return {
+    event: "error",
+    data: JSON.stringify({
+      code: "EngineFailure",
+      message: "Internal server error"
+    })
+  };
+}
+function heartbeatOptions(options) {
+  return {
+    intervalMs: options?.intervalMs ?? DEFAULT_SSE_HEARTBEAT_INTERVAL_MS,
+    schedule: options?.schedule ?? scheduleInterval,
+    now: options?.now ?? Date.now
+  };
+}
+export function createEventEnvelopeSSEStream(options) {
+  let cleanup = null;
+  return new ReadableStream({
+    start(controller) {
+      let closed = !1, clearHeartbeat = null;
+      const closeResources = async () => {
+        if (closed)
+          return;
+        closed = !0;
+        if (clearHeartbeat !== null) {
+          clearHeartbeat();
+          clearHeartbeat = null;
+        }
+        options.signal?.removeEventListener("abort", onAbort);
+        try {
+          await options.close();
+        } catch {}
+      };
+      cleanup = closeResources;
+      const enqueue = (frame) => {
+        if (closed)
+          return;
+        try {
+          controller.enqueue(encodeFrame(frame));
+        } catch {
+          closeResources();
+        }
+      }, onAbort = () => {
+        closeResources();
+      };
+      if (options.signal?.aborted) {
+        closeResources();
+        controller.close();
+        return;
+      }
+      options.signal?.addEventListener("abort", onAbort, { once: !0 });
+      const heartbeat = heartbeatOptions(options.heartbeat), enqueuePing = (data) => {
+        enqueue({
+          event: "ping",
+          data: JSON.stringify(data)
+        });
+      };
+      if (options.ready !== void 0)
+        options.ready.then(() => {
+          enqueuePing({ emittedAtMs: heartbeat.now(), replayComplete: !0 });
+          return;
+        }, () => {
+          return;
+        });
+      if (heartbeat.intervalMs > 0)
+        clearHeartbeat = heartbeat.schedule(() => {
+          enqueuePing({ emittedAtMs: heartbeat.now() });
+        }, heartbeat.intervalMs);
+      (async () => {
+        try {
+          for await (const envelope of options.iterable)
+            enqueue({
+              id: envelope.cursor,
+              event: envelope.kind,
+              data: JSON.stringify(envelope)
+            });
+        } catch (error) {
+          enqueue(sanitizedErrorFrame(error));
+        } finally {
+          await closeResources();
+          try {
+            controller.close();
+          } catch {}
+        }
+      })();
+    },
+    cancel() {
+      return cleanup?.();
+    }
+  });
+}
 export function createStoredChunkSSEStream(chunks, mapChunkToText) {
   return new ReadableStream({
     start(controller) {
@@ -21,13 +165,13 @@ export function createStoredChunkSSEStream(chunks, mapChunkToText) {
         const text = mapChunkToText(chunk);
         if (text === null)
           continue;
-        controller.enqueue(textEncoder.encode(formatSSE({
+        controller.enqueue(textEncoder.encode(formatServerSentEvent({
           id: String(chunk.sequence),
           event: "token",
           data: text
         })));
       }
-      controller.enqueue(textEncoder.encode(formatSSE({
+      controller.enqueue(textEncoder.encode(formatServerSentEvent({
         event: "done",
         data: ""
       })));
@@ -36,7 +180,8 @@ export function createStoredChunkSSEStream(chunks, mapChunkToText) {
   });
 }
 export const SSE_RESPONSE_HEADERS = {
-  "Content-Type": "text/event-stream",
-  "Cache-Control": "no-cache",
-  Connection: "keep-alive"
+  "Content-Type": "text/event-stream; charset=utf-8",
+  "Cache-Control": "no-cache, no-transform",
+  Connection: "keep-alive",
+  "X-Accel-Buffering": "no"
 };

package/dist/server/operations/start-or-signal-workflow.d.ts

@@ -13,6 +13,7 @@ declare const startOrSignalWorkflowInput: z.ZodObject<{
     tags: z.ZodOptional<z.ZodUnknown>;
     idempotencyKey: z.ZodOptional<z.ZodUnknown>;
     searchAttributes: z.ZodOptional<z.ZodUnknown>;
+    onTerminalConflict: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 declare const startOrSignalWorkflowOutput: z.ZodObject<{
     id: z.ZodString;
@@ -36,6 +37,7 @@ export declare const startOrSignalWorkflowOperation: import("../operation-catalo
     tags?: unknown;
     idempotencyKey?: unknown;
     searchAttributes?: unknown;
+    onTerminalConflict?: unknown;
 }, {
     id: string;
     outcome: "started" | "signalled";

package/dist/server/operations/start-or-signal-workflow.js

@@ -2,14 +2,15 @@ import { z } from "zod";
 import {
   IdempotencyKeyPurgedError,
   StartOrSignalConflictError,
-  WorkflowNotRegisteredError
+  WorkflowNotRegisteredError,
+  WorkflowTeardownPendingError
 } from "../../core/engine/errors.js";
 import { runtimeWorkflowEngine } from "../../core/runtime-workflow-engine.js";
 import { isSignalIdWithinByteLimit } from "../../core/signal-id.js";
 import { StartWorkflowValidationError } from "../../core/start-workflow-validation.js";
 import { defineOperation } from "../operation-registry.js";
 import { invalidParamsFault, shapeRestFault } from "./operation-helpers.js";
-import { buildSharedStartWorkflowOptions } from "./start-workflow-options.js";
+import { buildStartOrSignalWorkflowOptions } from "./start-workflow-options.js";
 import {
   extractSharedStartWorkflowRestFields,
   parseStartWorkflowRequestRecord
@@ -26,7 +27,8 @@ const startOrSignalWorkflowInput = z.object({
   startAfter: z.unknown().optional(),
   tags: z.unknown().optional(),
   idempotencyKey: z.unknown().optional(),
-  searchAttributes: z.unknown().optional()
+  searchAttributes: z.unknown().optional(),
+  onTerminalConflict: z.unknown().optional()
 }), startOrSignalWorkflowOutput = z.object({
   id: z.string(),
   outcome: z.enum(["started", "signalled"])
@@ -36,12 +38,12 @@ function validateStartOrSignalWorkflowInput(input, lookupSearchAttributeSchema)
     throw invalidParamsFault("Missing required field: type");
   let options;
   try {
-    options = buildSharedStartWorkflowOptions(input, lookupSearchAttributeSchema(input.type));
+    options = buildStartOrSignalWorkflowOptions(input, lookupSearchAttributeSchema(input.type));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw invalidParamsFault(message);
   }
-  assertConvergenceTokenProvided(input.signalId, options.idempotencyKey);
+  assertConvergenceTokenProvided(input.signalId, options);
   const signal = {
     name: input.signalName,
     payload: input.signalPayload,
@@ -49,22 +51,29 @@ function validateStartOrSignalWorkflowInput(input, lookupSearchAttributeSchema)
   };
   return { type: input.type, signal, options };
 }
-function assertConvergenceTokenProvided(signalId, idempotencyKey) {
-  if (signalId === void 0 && idempotencyKey === void 0)
+function assertConvergenceTokenProvided(signalId, options) {
+  if (options.onTerminalConflict === "start-new" && signalId === void 0)
+    throw invalidParamsFault("startOrSignal options.onTerminalConflict: 'start-new' requires signalId so concurrent restart-capable callers converge on one deterministic initial signal.");
+  if (signalId === void 0 && options.idempotencyKey === void 0)
     throw invalidParamsFault("startOrSignal requires either signalId or idempotencyKey to identify the signal to deliver. (Concurrent callers converge on one workflow and one signal only with a shared idempotencyKey, or a shared id plus signalId; a bare signalId starts a fresh run per caller.)");
-  if (signalId !== void 0 && idempotencyKey !== void 0)
+  if (signalId !== void 0 && options.idempotencyKey !== void 0)
     throw invalidParamsFault("startOrSignal does not accept both signalId and idempotencyKey: the signal id derives from the idempotency key for convergence. Provide exactly one.");
 }
 function resolveStartOrSignalWorkflowFault(error) {
   const message = error instanceof Error ? error.message : String(error);
   if (error instanceof WorkflowNotRegisteredError)
     throw invalidParamsFault(message, error.code);
-  if (error instanceof StartOrSignalConflictError || error instanceof IdempotencyKeyPurgedError)
+  if (error instanceof StartOrSignalConflictError || error instanceof IdempotencyKeyPurgedError || error instanceof WorkflowTeardownPendingError) {
+    const data = {
+      reason: message,
+      weftCode: error.code
+    };
     throw {
       code: "Conflict",
       message,
-      data: { reason: message, weftCode: error.code }
+      data
     };
+  }
   if (error instanceof StartWorkflowValidationError)
     throw invalidParamsFault(message);
   throw {
@@ -77,8 +86,8 @@ export const startOrSignalWorkflowOperation = defineOperation({
   name: "weft.workflows.startorsignal",
   mcpExposable: !1,
   summary: "Atomically start a workflow or signal it if it already exists",
-  description: 'Start a workflow or deliver a signal to 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 faults with Conflict, as does a spent `idempotencyKey` whose run was purged or swept by retention. Requires `type`, `signalName`, and exactly one of `signalId` or `idempotencyKey` (not both). Accepts `input`, `signalPayload`, and the non-idempotency start options from weft.workflows.start (`id`, `executionTimeout`, `startAt`/`startAfter`, `tags`, `searchAttributes`); `idempotencyKey` is governed solely by the "exactly one of" rule above. Returns the workflow `id`. Concurrent callers converge on one workflow and one signal only with a shared `idempotencyKey`, or a shared `id` plus `signalId`; a bare `signalId` (no `id`/`idempotencyKey`) starts a fresh run per caller and does not converge.',
-  destructive: !1,
+  description: 'Start a workflow or deliver a signal to 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 faults with Conflict unless `onTerminalConflict: "start-new"` is supplied with `id` and `signalId`, in which case the prior terminal run is replaced through the shared terminal-replacement path and the initial signal is delivered to the fresh run. A spent `idempotencyKey` whose run was purged or swept by retention also faults with Conflict. Requires `type`, `signalName`, and exactly one of `signalId` or `idempotencyKey` (not both). Accepts `input`, `signalPayload`, and the non-idempotency start options from weft.workflows.start (`id`, `executionTimeout`, `startAt`/`startAfter`, `tags`, `searchAttributes`) plus `onTerminalConflict`; `idempotencyKey` is governed by the "exactly one of" rule above and cannot be combined with restart. Returns the workflow `id`. Concurrent callers converge on one workflow and one signal only with a shared `idempotencyKey`, or a shared `id` plus `signalId`; a bare `signalId` (no `id`/`idempotencyKey`) starts a fresh run per caller and does not converge.',
+  destructive: !0,
   tags: ["Workflows", "Signals"],
   inputSchema: startOrSignalWorkflowInput,
   outputSchema: startOrSignalWorkflowOutput,
@@ -114,7 +123,8 @@ export const startOrSignalWorkflowOperation = defineOperation({
     startAfter: { kind: "body-field", bodyField: "startAfter" },
     tags: { kind: "body-field", bodyField: "tags" },
     idempotencyKey: { kind: "body-field", bodyField: "idempotencyKey" },
-    searchAttributes: { kind: "body-field", bodyField: "searchAttributes" }
+    searchAttributes: { kind: "body-field", bodyField: "searchAttributes" },
+    onTerminalConflict: { kind: "body-field", bodyField: "onTerminalConflict" }
   },
   extractInput: async (request, _pathParams, context) => {
     const record = await parseStartWorkflowRequestRecord(request, context);
@@ -122,7 +132,8 @@ export const startOrSignalWorkflowOperation = defineOperation({
       ...extractSharedStartWorkflowRestFields(record),
       signalName: record.signalName,
       signalPayload: record.signalPayload,
-      signalId: record.signalId
+      signalId: record.signalId,
+      onTerminalConflict: record.onTerminalConflict
     };
   },
   success: { kind: "json", status: 201 },

package/dist/server/operations/start-workflow-options.d.ts

@@ -1,4 +1,4 @@
-import type { SearchAttributeSchema, SearchAttributeValue, StartOptions } from '../../core/types.ts';
+import type { SearchAttributeSchema, SearchAttributeValue, StartOptions, StartOrSignalOptions } from '../../core/types.ts';
 /**
  * The raw, transport-supplied start-option fields shared by `weft.workflows.start`
  * and `weft.workflows.startorsignal`. Each is `unknown` because validation happens
@@ -14,6 +14,9 @@ export type SharedStartWorkflowOptionInput = {
     idempotencyKey?: unknown;
     searchAttributes?: unknown;
 };
+export type StartOrSignalWorkflowOptionInput = SharedStartWorkflowOptionInput & {
+    onTerminalConflict?: unknown;
+};
 /**
  * Coerce the shared start-option fields into a validated {@link StartOptions}.
  * Both start operations call this so they cannot drift in how they validate `id`,
@@ -21,13 +24,13 @@ export type SharedStartWorkflowOptionInput = {
  * `searchAttributes` (a new field added here covers both surfaces at once). Throws
  * {@link StartWorkflowValidationError} on any malformed field.
  *
- * `onTerminalConflict` is intentionally NOT part of this shared path: it is an
- * in-process `engine.start`-only policy (its purge-and-restart would make the
- * transport `weft.workflows.start` operation conditionally destructive and would
- * violate `startOrSignal`'s at-most-once identity), so it is not exposed over
- * REST/JSON-RPC. See follow-up issue #489.
+ * `onTerminalConflict` is intentionally NOT part of this shared path:
+ * `weft.workflows.start` remains non-restart-capable over transport. The
+ * start-or-signal operation adds its narrower restart policy through
+ * {@link buildStartOrSignalWorkflowOptions}.
  */
 export declare function buildSharedStartWorkflowOptions(input: SharedStartWorkflowOptionInput, searchAttributeSchema: SearchAttributeSchema | undefined): StartOptions;
+export declare function buildStartOrSignalWorkflowOptions(input: StartOrSignalWorkflowOptionInput, searchAttributeSchema: SearchAttributeSchema | undefined): StartOrSignalOptions;
 /**
  * Coerce a transport-supplied `searchAttributes` object into validated
  * {@link SearchAttributeValue}s. Shared by `weft.workflows.start` and

package/dist/server/operations/start-workflow-options.js

@@ -1,6 +1,7 @@
 import { validateAttributeType } from "../../core/search-attributes.js";
 import {
   assertExclusiveStartWorkflowOptions,
+  assertValidOnTerminalConflict,
   coerceStartWorkflowDuration,
   coerceStartWorkflowId,
   coerceStartWorkflowIdempotencyKey,
@@ -27,6 +28,18 @@ export function buildSharedStartWorkflowOptions(input, searchAttributeSchema) {
   assertExclusiveStartWorkflowOptions(options.startAt, options.startAfter);
   return options;
 }
+export function buildStartOrSignalWorkflowOptions(input, searchAttributeSchema) {
+  const options = buildSharedStartWorkflowOptions(input, searchAttributeSchema);
+  if (input.onTerminalConflict !== void 0)
+    options.onTerminalConflict = coerceStartOrSignalOnTerminalConflict(input.onTerminalConflict, 'Field "onTerminalConflict"');
+  assertValidOnTerminalConflict(options);
+  return options;
+}
+function coerceStartOrSignalOnTerminalConflict(value, fieldName) {
+  if (value === "error" || value === "start-new")
+    return value;
+  throw new StartWorkflowValidationError(`${fieldName} must be "error" or "start-new"`);
+}
 export function coerceStartWorkflowSearchAttributes(value, fieldName, schema) {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     throw new StartWorkflowValidationError(`${fieldName} must be an object`);

package/dist/server/operations/workflow-events-sse.d.ts

@@ -0,0 +1,17 @@
+import type { UnknownRestBinding } from '../rest-bindings.ts';
+import type { WorkflowStreamConnectionLease } from '../runtime/websocket-stream.ts';
+import { type EventEnvelope, type WorkflowEventFeed } from '../workflow-event-feed.ts';
+export type WorkflowStreamConnectionAcquirer = (workflowId: string) => WorkflowStreamConnectionLease | null;
+export type EventStreamOperationContext = {
+    readonly workflowEventFeed?: WorkflowEventFeed;
+    readonly acquireWorkflowStreamConnection?: WorkflowStreamConnectionAcquirer;
+};
+type WorkflowEventsSseOutput = AsyncIterable<EventEnvelope>;
+export declare const workflowEventsSseOperation: import("../operation-catalog.ts").OperationDefinition<{
+    workflowId: string;
+    selector: "events" | "tokens";
+    fromCursor?: string | undefined;
+    lastEventId?: string | undefined;
+}, WorkflowEventsSseOutput, EventEnvelope>;
+export declare const workflowEventsSseRestBinding: UnknownRestBinding;
+export {};