@lostgradient/weft 0.6.0 → 0.8.0

package/dist/client/open-event-subscription.d.ts

@@ -10,7 +10,8 @@
  * @module client/open-event-subscription
  */
 import type { WorkflowEvent } from '../core/types.ts';
-import { WorkflowEventSubscription, type WorkflowEventStreamOptions } from './event-stream.ts';
+import type { WorkflowEventStreamOptions } from './event-stream-options.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
 /**
  * The streaming-relevant view of an HTTP client: the fields a workflow event
  * subscription needs to open its `/watch` socket and run `getEvents` catch-up.
@@ -30,4 +31,4 @@ export type WorkflowEventStreamHost = {
  * consumers (`tail()`) so the connect catch-up is buffered for the async
  * iterator rather than dropped.
  */
-export declare function openClientEventSubscription(host: WorkflowEventStreamHost, streamOptions: WorkflowEventStreamOptions, workflowId: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventSubscription;
+export declare function openClientEventSubscription(host: WorkflowEventStreamHost, streamOptions: WorkflowEventStreamOptions, workflowId: string, onEvent: (event: WorkflowEvent) => void, bufferForIteration?: boolean): WorkflowEventTail;

package/dist/client/open-event-subscription.js

@@ -1,5 +1,32 @@
+import { detectRuntime } from "../runtime/portable.js";
 import { workflowWatchWebSocketUrl } from "./event-stream-transport.js";
 import { WorkflowEventSubscription } from "./event-stream.js";
+import { SseWorkflowEventSubscription, workflowEventsSseUrl } from "./sse-event-stream.js";
 export function openClientEventSubscription(host, streamOptions, workflowId, onEvent, bufferForIteration = !1) {
-  return new WorkflowEventSubscription(workflowWatchWebSocketUrl(host.baseUrl, workflowId), host.headers, workflowId, (id) => host.getEvents(id), onEvent, bufferForIteration ? { ...streamOptions, bufferForIteration } : streamOptions);
+  const options = bufferForIteration ? { ...streamOptions, bufferForIteration } : streamOptions, transport = options.eventTransport ?? "auto";
+  if (transport === "sse")
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  if (shouldPreferServerSentEventsFallback(host, options, transport))
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  try {
+    return new WorkflowEventSubscription(workflowWatchWebSocketUrl(host.baseUrl, workflowId), host.headers, workflowId, (id) => host.getEvents(id), onEvent, options);
+  } catch (error) {
+    if (transport !== "auto")
+      throw error;
+    if (!isWebSocketTransportUnavailable(error))
+      throw error;
+    return openSseEventSubscription(host, workflowId, onEvent, options);
+  }
+}
+function shouldPreferServerSentEventsFallback(host, options, transport) {
+  return transport === "auto" && options.webSocketFactory === void 0 && detectRuntime() !== "bun" && Object.keys(host.headers).length > 0;
+}
+function isWebSocketTransportUnavailable(error) {
+  if (!(error instanceof Error))
+    return !1;
+  const message = error.message.toLowerCase();
+  return message.includes("no global websocket") || message.includes("cannot send the configured auth headers over websocket") || message.includes("websocket headers unavailable") || message.includes("websocket constructor has no header support") || message.includes("provide httpclientoptions.websocketfactory");
+}
+function openSseEventSubscription(host, workflowId, onEvent, options) {
+  return new SseWorkflowEventSubscription(workflowEventsSseUrl(host.baseUrl, workflowId), host.headers, workflowId, onEvent, options);
 }

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

@@ -0,0 +1,27 @@
+import type { WorkflowEvent } from '../core/types.ts';
+import type { StreamCloseReason } from './event-stream.ts';
+import type { WorkflowEventTail } from './event-tail.ts';
+export type ServerSentEventFrame = {
+    readonly id?: string;
+    readonly event?: string;
+    readonly data: string;
+};
+export type ServerSentEventParseResult = {
+    readonly frames: ReadonlyArray<ServerSentEventFrame>;
+    readonly remainder: string;
+};
+export type SseWorkflowEventStreamOptions = {
+    readonly maxReconnectAttempts?: number;
+    readonly reconnectBackoffMs?: number;
+    readonly bufferForIteration?: boolean;
+};
+export declare function workflowEventsSseUrl(baseUrl: string, workflowId: string): string;
+export declare function parseServerSentEventChunk(text: string, previousRemainder?: string): ServerSentEventParseResult;
+export declare class SseWorkflowEventSubscription implements WorkflowEventTail {
+    #private;
+    constructor(url: string, headers: Record<string, string>, workflowId: string, onEvent: (event: WorkflowEvent) => void, options?: SseWorkflowEventStreamOptions);
+    get closeReason(): StreamCloseReason | null;
+    whenConnected(): Promise<void>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<WorkflowEvent>;
+}

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

@@ -0,0 +1,276 @@
+import { WORKFLOW_TERMINAL_EVENT_TYPES } from "../core/events/workflow-events.js";
+import { WorkflowEventTailLifecycle } from "./event-tail-lifecycle.js";
+const DEFAULT_MAX_RECONNECT_ATTEMPTS = 5, DEFAULT_RECONNECT_BACKOFF_MS = 50;
+export function workflowEventsSseUrl(baseUrl, workflowId) {
+  return `${baseUrl.replace(/\/+$/, "")}/v1/workflows/${encodeURIComponent(workflowId)}/events/sse`;
+}
+export function parseServerSentEventChunk(text, previousRemainder = "") {
+  const parts = `${previousRemainder}${text}`.replaceAll(`\r
+`, `
+`).replaceAll("\r", `
+`).split(`
+
+`), remainder = parts.pop() ?? "";
+  return { frames: parts.map(parseServerSentEventFrame).filter((frame) => frame !== null), remainder };
+}
+function parseServerSentEventFrame(block) {
+  const parts = {
+    id: void 0,
+    event: void 0,
+    dataLines: []
+  };
+  for (const rawLine of block.split(`
+`))
+    applyServerSentEventLine(parts, rawLine);
+  return frameFromParts(parts);
+}
+function applyServerSentEventLine(parts, rawLine) {
+  if (rawLine === "" || rawLine.startsWith(":"))
+    return;
+  const { field, value } = splitServerSentEventLine(rawLine);
+  if (field === "id")
+    parts.id = value;
+  else if (field === "event")
+    parts.event = value;
+  else if (field === "data")
+    parts.dataLines.push(value);
+}
+function splitServerSentEventLine(rawLine) {
+  const separator = rawLine.indexOf(":"), field = separator === -1 ? rawLine : rawLine.slice(0, separator), rawValue = separator === -1 ? "" : rawLine.slice(separator + 1);
+  return {
+    field,
+    value: rawValue.startsWith(" ") ? rawValue.slice(1) : rawValue
+  };
+}
+function frameFromParts(parts) {
+  if (parts.id === void 0 && parts.event === void 0 && parts.dataLines.length === 0)
+    return null;
+  return {
+    ...parts.id === void 0 ? {} : { id: parts.id },
+    ...parts.event === void 0 ? {} : { event: parts.event },
+    data: parts.dataLines.join(`
+`)
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseWorkflowEventEnvelope(data) {
+  const parsed = parseJson(data);
+  if (!isRecord(parsed))
+    return null;
+  return workflowEventEnvelopeFromRecord(parsed);
+}
+function isReplayCompletePing(data) {
+  const parsed = parseJson(data);
+  return isRecord(parsed) && parsed.replayComplete === !0;
+}
+function parseJson(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+function workflowEventEnvelopeFromRecord(parsed) {
+  if (typeof parsed.kind !== "string")
+    return null;
+  if (typeof parsed.workflowId !== "string")
+    return null;
+  if (!isWorkflowEventSelector(parsed.selector))
+    return null;
+  const sequence = finiteNumber(parsed.sequence);
+  if (sequence === null)
+    return null;
+  if (typeof parsed.cursor !== "string")
+    return null;
+  const emittedAtMs = finiteNumber(parsed.emittedAtMs);
+  if (emittedAtMs === null)
+    return null;
+  if (!Object.hasOwn(parsed, "payload"))
+    return null;
+  return {
+    kind: parsed.kind,
+    workflowId: parsed.workflowId,
+    selector: parsed.selector,
+    sequence,
+    cursor: parsed.cursor,
+    emittedAtMs,
+    payload: parsed.payload
+  };
+}
+function isWorkflowEventSelector(value) {
+  return value === "events" || value === "tokens";
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function envelopeToWorkflowEvent(envelope) {
+  return {
+    type: envelope.kind,
+    timestamp: envelope.emittedAtMs,
+    data: isRecord(envelope.payload) ? envelope.payload : { value: envelope.payload }
+  };
+}
+function isEventStreamResponse(response) {
+  const contentType = response.headers.get("Content-Type");
+  if (contentType === null)
+    return !1;
+  return contentType.split(";", 1)[0]?.trim().toLowerCase() === "text/event-stream";
+}
+
+export class SseWorkflowEventSubscription {
+  #url;
+  #headers;
+  #workflowId;
+  #onEvent;
+  #maxReconnectAttempts;
+  #reconnectBackoffMs;
+  #lifecycle;
+  #connected = Promise.withResolvers();
+  #abortController = null;
+  #reconnectAttempts = 0;
+  #reconnectTimer = null;
+  #lastEventId = null;
+  constructor(url, headers, workflowId, onEvent, options) {
+    this.#url = url;
+    this.#headers = headers;
+    this.#workflowId = workflowId;
+    this.#onEvent = onEvent;
+    this.#maxReconnectAttempts = options?.maxReconnectAttempts ?? DEFAULT_MAX_RECONNECT_ATTEMPTS;
+    this.#reconnectBackoffMs = options?.reconnectBackoffMs ?? DEFAULT_RECONNECT_BACKOFF_MS;
+    this.#lifecycle = new WorkflowEventTailLifecycle({
+      bufferForIteration: options?.bufferForIteration ?? !1,
+      onClose: (reason) => this.#onLifecycleClose(reason)
+    });
+    this.#connect();
+  }
+  get closeReason() {
+    return this.#lifecycle.closeReason;
+  }
+  whenConnected() {
+    return this.#connected.promise;
+  }
+  async#connect() {
+    if (this.#lifecycle.closed)
+      return;
+    const abortController = new AbortController;
+    this.#abortController = abortController;
+    try {
+      const response = await fetch(this.#url, {
+        headers: this.#requestHeaders(),
+        signal: abortController.signal
+      });
+      if (!response.ok || response.body === null) {
+        this.#terminate("server-error");
+        return;
+      }
+      if (!isEventStreamResponse(response)) {
+        this.#terminate("server-error");
+        return;
+      }
+      await this.#readResponseBody(response.body);
+      if (!this.#lifecycle.closed)
+        this.#scheduleReconnect();
+    } catch {
+      if (!this.#lifecycle.closed)
+        this.#scheduleReconnect();
+    } finally {
+      if (this.#abortController === abortController)
+        this.#abortController = null;
+    }
+  }
+  #requestHeaders() {
+    const headers = new Headers(this.#headers);
+    headers.set("Accept", "text/event-stream");
+    headers.set("Cache-Control", "no-cache");
+    if (this.#lastEventId !== null)
+      headers.set("Last-Event-ID", this.#lastEventId);
+    return headers;
+  }
+  async#readResponseBody(body) {
+    const reader = body.getReader(), decoder = new TextDecoder;
+    let remainder = "";
+    try {
+      while (!this.#lifecycle.closed) {
+        const chunk = await reader.read();
+        if (chunk.done)
+          return;
+        const parsed = parseServerSentEventChunk(decoder.decode(chunk.value, { stream: !0 }), remainder);
+        remainder = parsed.remainder;
+        for (const frame of parsed.frames) {
+          const handling = this.#handleFrame(frame);
+          if (this.#lifecycle.closed || handling === "server-error")
+            return;
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  #handleFrame(frame) {
+    if (frame.event === "ping") {
+      this.#markHealthyFrame();
+      if (isReplayCompletePing(frame.data))
+        this.#markConnected();
+      return "healthy";
+    }
+    if (frame.event === "error") {
+      this.#terminate("server-error");
+      return "server-error";
+    }
+    const envelope = parseWorkflowEventEnvelope(frame.data);
+    if (envelope === null)
+      return "ignored";
+    if (envelope.workflowId !== this.#workflowId)
+      return "ignored";
+    this.#lastEventId = frame.id ?? envelope.cursor;
+    this.#markHealthyFrame();
+    this.#emit(envelopeToWorkflowEvent(envelope));
+    return "healthy";
+  }
+  #emit(event) {
+    if (!this.#lifecycle.emit(event, this.#onEvent))
+      return;
+    if (WORKFLOW_TERMINAL_EVENT_TYPES.has(event.type))
+      this.#terminate("workflow-terminal");
+  }
+  #scheduleReconnect() {
+    if (this.#lifecycle.closed || this.#reconnectTimer !== null)
+      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);
+  }
+  #markConnected() {
+    this.#connected.resolve();
+  }
+  #markHealthyFrame() {
+    this.#reconnectAttempts = 0;
+  }
+  #terminate(reason) {
+    this.#lifecycle.terminate(reason);
+  }
+  #onLifecycleClose(_reason) {
+    this.#markConnected();
+    if (this.#reconnectTimer !== null) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
+    this.#abortController?.abort();
+    this.#abortController = null;
+  }
+  close() {
+    this.#lifecycle.close();
+  }
+  [Symbol.asyncIterator]() {
+    return this.#lifecycle[Symbol.asyncIterator]();
+  }
+}

package/dist/client/start-body.d.ts

@@ -1,5 +1,5 @@
 import type { ScheduleSpec, StartOrSignalSignal } from '../core/types.ts';
-import type { ClientStartOptions } from './interface.ts';
+import type { ClientStartOptions, ClientStartOrSignalOptions } from './interface.ts';
 export declare function setIfDefined(body: Record<string, unknown>, key: string, value: unknown): void;
 /**
  * Translate a schedule recurrence specification into the wire body fields the
@@ -13,4 +13,4 @@ export declare function buildStartBody(type: string, input: unknown, options?: C
  * spec into `signalName` / `signalPayload` / `signalId` and carries the same
  * start options as {@link buildStartBody}.
  */
-export declare function buildStartOrSignalBody(type: string, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOptions): Record<string, unknown>;
+export declare function buildStartOrSignalBody(type: string, input: unknown, signal: StartOrSignalSignal, options?: ClientStartOrSignalOptions): Record<string, unknown>;

package/dist/client/start-body.js

@@ -28,5 +28,6 @@ export function buildStartOrSignalBody(type, input, signal, options) {
   setIfDefined(body, "signalPayload", signal.payload);
   setIfDefined(body, "signalId", signal.signalId);
   applyStartOptionsToBody(body, options);
+  setIfDefined(body, "onTerminalConflict", options?.onTerminalConflict);
   return body;
 }

package/dist/core/context/activity-retry-state.d.ts

@@ -10,6 +10,7 @@ import type { ContextInternals } from './internals.ts';
 export declare const ACTIVITY_RETRY_STATE_LOCAL_KEY = "__weftActivityRetryState";
 declare const ACTIVITY_RETRY_STATE_VERSION = 1;
 export declare const MAX_CHECKPOINTED_RETRY_ATTEMPT = 10000;
+export type ActivityRetryStateKey = number | string;
 export interface ActivityRetryState {
     version: typeof ACTIVITY_RETRY_STATE_VERSION;
     attempts: Record<string, number>;
@@ -24,15 +25,15 @@ export interface ActivityRetryState {
     dispatchedAt?: Record<string, number>;
 }
 export declare function isActivityRetryState(value: unknown): value is ActivityRetryState;
-export declare function readActivityRetryAttempt(internals: ContextInternals, step: number): number | undefined;
-export declare function readCompletedRetrySleepCount(internals: ContextInternals, step: number): number;
-export declare function writeActivityRetryAttempt(internals: ContextInternals, step: number, attempt: number): void;
-export declare function completeActivityRetryAttempt(internals: ContextInternals, step: number, completedRetrySleepCount: number): void;
+export declare function readActivityRetryAttempt(internals: ContextInternals, key: ActivityRetryStateKey): number | undefined;
+export declare function readCompletedRetrySleepCount(internals: ContextInternals, key: ActivityRetryStateKey): number;
+export declare function writeActivityRetryAttempt(internals: ContextInternals, key: ActivityRetryStateKey, attempt: number): void;
+export declare function completeActivityRetryAttempt(internals: ContextInternals, key: ActivityRetryStateKey, completedRetrySleepCount: number): void;
 /**
  * Read the first-dispatch anchor for a step's `scheduleToCloseTimeout`, writing
  * `now` on the first dispatch. Read-first so a crash/replay never resets the
  * window: the budget is measured from the original dispatch, and the anchor
  * lands in the checkpoint committed at the dispatch `yield` that follows.
  */
-export declare function readOrInitActivityDispatchedAt(internals: ContextInternals, step: number, now: number): number;
+export declare function readOrInitActivityDispatchedAt(internals: ContextInternals, key: ActivityRetryStateKey, now: number): number;
 export {};

package/dist/core/context/activity-retry-state.js

@@ -7,29 +7,39 @@ function isRecord(value) {
 export function isActivityRetryState(value) {
   return isRecord(value) && value.version === ACTIVITY_RETRY_STATE_VERSION && isRecord(value.attempts) && (value.completedRetrySleeps === void 0 || isRecord(value.completedRetrySleeps)) && (value.dispatchedAt === void 0 || isRecord(value.dispatchedAt));
 }
-function assertValidRetryAttempt(attempt, step) {
+function retryStateSlotKey(key) {
+  if (typeof key === "number")
+    return String(key);
+  if (key.length === 0)
+    throw Error("Invalid empty checkpointed activity retry state key");
+  return key;
+}
+function retryStateKeyLabel(key) {
+  return typeof key === "number" ? `step ${String(key)}` : `key ${key}`;
+}
+function assertValidRetryAttempt(attempt, key) {
   if (!Number.isInteger(attempt) || attempt <= 1 || attempt > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid checkpointed activity retry attempt ${String(attempt)} for step ${String(step)}`);
+    throw Error(`Invalid checkpointed activity retry attempt ${String(attempt)} for ${retryStateKeyLabel(key)}`);
 }
-export function readActivityRetryAttempt(internals, step) {
+export function readActivityRetryAttempt(internals, key) {
   const state = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
   if (!isActivityRetryState(state))
     return;
-  const attempt = state.attempts[String(step)];
+  const attempt = state.attempts[retryStateSlotKey(key)];
   if (attempt === void 0)
     return;
-  assertValidRetryAttempt(attempt, step);
+  assertValidRetryAttempt(attempt, key);
   return attempt;
 }
-export function readCompletedRetrySleepCount(internals, step) {
+export function readCompletedRetrySleepCount(internals, key) {
   const state = internals.checkpointLocals[ACTIVITY_RETRY_STATE_LOCAL_KEY];
   if (!isActivityRetryState(state))
     return 0;
-  const count = state.completedRetrySleeps?.[String(step)];
+  const count = state.completedRetrySleeps?.[retryStateSlotKey(key)];
   if (count === void 0)
     return 0;
   if (!Number.isInteger(count) || count < 0 || count > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid checkpointed activity retry sleep count ${String(count)} for step ${String(step)}`);
+    throw Error(`Invalid checkpointed activity retry sleep count ${String(count)} for ${retryStateKeyLabel(key)}`);
   return count;
 }
 function currentRetryState(internals) {
@@ -52,38 +62,38 @@ function writeRetryStateSlot(internals, attempts, completedRetrySleeps, dispatch
     }
   };
 }
-export function writeActivityRetryAttempt(internals, step, attempt) {
-  assertValidRetryAttempt(attempt, step);
+export function writeActivityRetryAttempt(internals, key, attempt) {
+  assertValidRetryAttempt(attempt, key);
   const current = currentRetryState(internals), attempts = current ? { ...current.attempts } : {};
-  attempts[String(step)] = attempt;
+  attempts[retryStateSlotKey(key)] = attempt;
   writeRetryStateSlot(internals, attempts, current?.completedRetrySleeps, current?.dispatchedAt);
 }
-function clearActivityRetryAttempt(internals, step) {
+function clearActivityRetryAttempt(internals, key) {
   const current = currentRetryState(internals);
   if (!current)
     return;
   const attempts = { ...current.attempts };
-  delete attempts[String(step)];
+  delete attempts[retryStateSlotKey(key)];
   writeRetryStateSlot(internals, attempts, current.completedRetrySleeps, current.dispatchedAt);
 }
-export function completeActivityRetryAttempt(internals, step, completedRetrySleepCount) {
+export function completeActivityRetryAttempt(internals, key, completedRetrySleepCount) {
   if (!Number.isInteger(completedRetrySleepCount) || completedRetrySleepCount < 0 || completedRetrySleepCount > MAX_CHECKPOINTED_RETRY_ATTEMPT)
-    throw Error(`Invalid completed activity retry sleep count ${String(completedRetrySleepCount)} for step ${String(step)}`);
-  clearActivityRetryAttempt(internals, step);
+    throw Error(`Invalid completed activity retry sleep count ${String(completedRetrySleepCount)} for ${retryStateKeyLabel(key)}`);
+  clearActivityRetryAttempt(internals, key);
   if (completedRetrySleepCount === 0)
     return;
   const current = currentRetryState(internals), attempts = current ? { ...current.attempts } : {}, completedRetrySleeps = current ? { ...current.completedRetrySleeps } : {};
-  completedRetrySleeps[String(step)] = completedRetrySleepCount;
+  completedRetrySleeps[retryStateSlotKey(key)] = completedRetrySleepCount;
   writeRetryStateSlot(internals, attempts, completedRetrySleeps, current?.dispatchedAt);
 }
-export function readOrInitActivityDispatchedAt(internals, step, now) {
-  const current = currentRetryState(internals), existing = current?.dispatchedAt?.[String(step)];
+export function readOrInitActivityDispatchedAt(internals, key, now) {
+  const current = currentRetryState(internals), slotKey = retryStateSlotKey(key), existing = current?.dispatchedAt?.[slotKey];
   if (typeof existing === "number" && Number.isFinite(existing))
     return existing;
   if (existing !== void 0)
-    throw Error(`Invalid checkpointed activity dispatch anchor ${String(existing)} for step ${String(step)}`);
+    throw Error(`Invalid checkpointed activity dispatch anchor ${String(existing)} for ${retryStateKeyLabel(key)}`);
   const attempts = current ? { ...current.attempts } : {}, dispatchedAt = current?.dispatchedAt ? { ...current.dispatchedAt } : {};
-  dispatchedAt[String(step)] = now;
+  dispatchedAt[slotKey] = now;
   writeRetryStateSlot(internals, attempts, current?.completedRetrySleeps, dispatchedAt);
   return now;
 }

package/dist/core/context/durable-activity.d.ts

@@ -0,0 +1,117 @@
+import type { ActivityCallable, ActivityCallOptions } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+type BareActivityFunction<TInput, TResult> = ((input: TInput) => Promise<TResult> | TResult) & {
+    execute?: never;
+};
+type BareNoInputActivityFunction<TResult> = (() => Promise<TResult> | TResult) & {
+    execute?: never;
+};
+export type DurableActivityInput = string | ActivityCallable<void, unknown> | BareNoInputActivityFunction<unknown> | ActivityCallable<unknown, unknown> | BareActivityFunction<unknown, unknown>;
+export interface DurableActivityInvocation {
+    activity: DurableActivityInput;
+    arguments: readonly unknown[];
+    callerStack: string;
+}
+export interface DurableActivityScope {
+    dispatch<TResult>(invocation: DurableActivityInvocation): Promise<TResult>;
+}
+/**
+ * Thrown when `durableActivity()` is called without an active inline `ctx.memo`
+ * durable-activity scope, or after that scope has already closed.
+ *
+ * The error usually means helper code escaped the memo callback boundary, ran
+ * under Worker execution mode, or started a helper activity without awaiting it
+ * before the memo callback returned.
+ *
+ * @example
+ * ```ts
+ * import { durableActivity, DurableActivityScopeError } from '@lostgradient/weft';
+ *
+ * async function sendOutsideWorkflow(): Promise<void> {
+ *   try {
+ *     await durableActivity('sendEmail', { userId: 'user-1' });
+ *   } catch (error) {
+ *     if (error instanceof DurableActivityScopeError) {
+ *       console.error(error.message);
+ *     }
+ *   }
+ * }
+ *
+ * void sendOutsideWorkflow;
+ * ```
+ */
+export declare class DurableActivityScopeError extends WeftError<'DurableActivityScopeError'> {
+    constructor(message: string);
+}
+/**
+ * Thrown when helper-launched activity code reaches an activity feature that
+ * cannot safely be represented inside a plain async memo callback.
+ *
+ * The first unsupported feature is `ActivityContext.completeAsync()`: async
+ * activity completion must use `yield* ctx.run()` directly so the parked
+ * completion token stays attached to a normal workflow operation.
+ *
+ * @example
+ * ```ts
+ * import { durableActivity, DurableActivityUnsupportedError, workflow } from '@lostgradient/weft';
+ *
+ * export const completionWorkflow = workflow({ name: 'manual-completion' }).execute(async function* (
+ *   ctx,
+ * ) {
+ *   try {
+ *     yield* ctx.memo('manual-completion-helper', async () =>
+ *       durableActivity('manualCompletionActivity', undefined, {
+ *         idempotencyKey: 'manual-completion:1',
+ *       }),
+ *     );
+ *   } catch (error) {
+ *     if (error instanceof DurableActivityUnsupportedError) {
+ *       console.error(error.message);
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare class DurableActivityUnsupportedError extends WeftError<'DurableActivityUnsupportedError'> {
+    constructor(message: string);
+}
+export declare function runWithDurableActivityScope<TResult>(scope: DurableActivityScope, execute: () => TResult): TResult;
+/**
+ * Run a durable activity from plain async helper code while an inline workflow
+ * is executing a `ctx.memo()` callback.
+ *
+ * `durableActivity()` gives shared async helpers the same activity dispatch
+ * machinery as `yield* ctx.run()` without converting the helper stack to
+ * generators. It is intentionally scoped: call it only from code awaited by one
+ * inline `ctx.memo()` callback, and await each helper activity sequentially
+ * before the callback returns. Activities with `idempotencyKey` get immediate
+ * lease-fenced result durability for the crash window between the activity
+ * returning and the memo checkpoint commit; unkeyed helper activities keep the
+ * normal at-least-once crash behavior.
+ *
+ * @example
+ * ```ts
+ * import { durableActivity, workflow } from '@lostgradient/weft';
+ *
+ * async function reserveInventory(input: { orderId: string }): Promise<{ reservationId: string }> {
+ *   return { reservationId: input.orderId };
+ * }
+ *
+ * export const checkout = workflow({ name: 'checkout' }).execute(async function* (
+ *   ctx,
+ *   input: { orderId: string },
+ * ) {
+ *   return yield* ctx.memo('reserve-inventory', async () =>
+ *     durableActivity(reserveInventory, { orderId: input.orderId }, {
+ *       idempotencyKey: `reserve:${input.orderId}`,
+ *     }),
+ *   );
+ * });
+ * ```
+ */
+export declare function durableActivity<TResult = unknown>(name: string, input?: unknown, options?: ActivityCallOptions): Promise<TResult>;
+export declare function durableActivity<TResult>(fn: ActivityCallable<void, TResult>, options?: ActivityCallOptions): Promise<TResult>;
+export declare function durableActivity<TResult>(fn: BareNoInputActivityFunction<TResult>, options?: ActivityCallOptions): Promise<TResult>;
+export declare function durableActivity<TInput, TResult>(fn: ActivityCallable<TInput, TResult>, input: TInput, options?: ActivityCallOptions): Promise<TResult>;
+export declare function durableActivity<TInput, TResult>(fn: BareActivityFunction<TInput, TResult>, input: TInput, options?: ActivityCallOptions): Promise<TResult>;
+export {};