@lostgradient/weft 0.11.0 → 0.13.0

package/dist/server/rest-bindings.d.ts

@@ -29,9 +29,8 @@ import type { TaskQueue } from './task-queue.ts';
 export type UnknownRestBinding = RestBinding<any, any>;
 /**
  * Static REST bindings for all operations that do not need per-server
- * configuration. The `weft.system.metrics` binding is excluded here
- * because it is constructed per-server via `createGetSystemMetricsRestBinding`
- * (to receive the metrics collector without module-level singletons).
+ * configuration. The `weft.system.metrics` binding is excluded because its
+ * factory receives the per-server metrics collector.
  * Use `createLiveRestBindings()` to get the full set for a given server.
  */
 export declare const REST_BINDINGS: ReadonlyArray<UnknownRestBinding>;
@@ -43,16 +42,6 @@ export declare const REST_BINDINGS: ReadonlyArray<UnknownRestBinding>;
  * are wired into the operations through {@link createLiveOperationRegistry}.
  */
 export declare function createLiveRestBindings(): ReadonlyArray<UnknownRestBinding>;
-/**
- * Live operation registry — populated with every operation that has a
- * `RestBinding`, a JSON-RPC mount, or an stdio mount. Exposed via a
- * factory so tests can spin up a fresh registry without inheriting
- * the live one's state.
- *
- * Concrete `OperationDefinition<Input, Output>` values are directly
- * assignable to `RegistrableOperation` by the variance design in
- * `operation-catalog.ts` — no `as ErasedOperation` cast is needed.
- */
 /**
  * Create the live operation registry for a server instance.
  *

package/dist/server/rest-bindings.js

@@ -7,12 +7,7 @@ import {
   aggregateWorkflowsOperation,
   aggregateWorkflowsRestBinding
 } from "./operations/aggregate-workflows.js";
-import {
-  completeAsyncActivityOperation,
-  completeAsyncActivityRestBinding,
-  failAsyncActivityOperation,
-  failAsyncActivityRestBinding
-} from "./operations/async-activity.js";
+import * as asyncActivity from "./operations/async-activity.js";
 import {
   bulkCancelWorkflowsOperation,
   bulkCancelWorkflowsRestBinding
@@ -66,6 +61,10 @@ import {
   getStreamChunksOperation,
   getStreamChunksRestBinding
 } from "./operations/get-stream-chunks.js";
+import {
+  getSystemLeaseOperation,
+  getSystemLeaseRestBinding
+} from "./operations/get-system-lease.js";
 import {
   createGetSystemMetricsOperation,
   createGetSystemMetricsRestBinding
@@ -89,6 +88,7 @@ import {
   getWorkflowEventsOperation,
   getWorkflowEventsRestBinding
 } from "./operations/get-workflow-events.js";
+import * as workflowObservability from "./operations/get-workflow-observability.js";
 import {
   getWorkflowResultOperation,
   getWorkflowResultRestBinding
@@ -155,6 +155,7 @@ import {
   startOrSignalWorkflowRestBinding
 } from "./operations/start-or-signal-workflow.js";
 import { startWorkflowOperation, startWorkflowRestBinding } from "./operations/start-workflow.js";
+import * as storageCapabilities from "./operations/storage-capabilities.js";
 import {
   storageBatchOperation,
   storageBatchRestBinding,
@@ -228,11 +229,13 @@ export const REST_BINDINGS = [
   cancelWorkflowRestBinding,
   getWorkflowResultRestBinding,
   getWorkflowAttributesRestBinding,
+  ...workflowObservability.workflowObservabilityRestBindings,
   getWorkflowEventsRestBinding,
   setWorkflowAttributesRestBinding,
   signalWorkflowRestBinding,
-  completeAsyncActivityRestBinding,
-  failAsyncActivityRestBinding,
+  asyncActivity.listPendingAsyncActivitiesRestBinding,
+  asyncActivity.completeAsyncActivityRestBinding,
+  asyncActivity.failAsyncActivityRestBinding,
   queryWorkflowRestBinding,
   queryWorkflowWithInputRestBinding,
   resumeWorkflowRestBinding,
@@ -243,6 +246,7 @@ export const REST_BINDINGS = [
   createScheduleRestBinding,
   updateScheduleRestBinding,
   getRegistryRestBinding,
+  getSystemLeaseRestBinding,
   getRetentionOverviewRestBinding,
   getUpdateResultRestBinding,
   listReviewsRestBinding,
@@ -265,6 +269,7 @@ export const REST_BINDINGS = [
   listSchedulesRestBinding,
   getScheduleRestBinding,
   replayWorkflowRestBinding,
+  storageCapabilities.storageCapabilitiesRestBinding,
   storageGetRestBinding,
   storagePutRestBinding,
   storageDeleteRestBinding,
@@ -357,11 +362,13 @@ export function createLiveOperationRegistry(options) {
     cancelWorkflowOperation,
     getWorkflowResultOperation,
     getWorkflowAttributesOperation,
+    ...workflowObservability.workflowObservabilityOperations,
     getWorkflowEventsOperation,
     setWorkflowAttributesOperation,
     signalWorkflowOperation,
-    completeAsyncActivityOperation,
-    failAsyncActivityOperation,
+    asyncActivity.listPendingAsyncActivitiesOperation,
+    asyncActivity.completeAsyncActivityOperation,
+    asyncActivity.failAsyncActivityOperation,
     queryWorkflowOperation,
     resumeWorkflowOperation,
     suspendWorkflowOperation,
@@ -371,6 +378,7 @@ export function createLiveOperationRegistry(options) {
     createScheduleOperation,
     updateScheduleOperation,
     getRegistryOperation,
+    getSystemLeaseOperation,
     getRetentionOverviewOperation,
     getUpdateResultOperation,
     listReviewsOperation,
@@ -395,6 +403,7 @@ export function createLiveOperationRegistry(options) {
     listSchedulesOperation,
     getScheduleOperation,
     replayWorkflowOperation,
+    storageCapabilities.storageCapabilitiesOperation,
     storageGetOperation,
     storagePutOperation,
     storageDeleteOperation,

package/dist/server/runtime/authentication-bridge.d.ts

@@ -1,12 +1,12 @@
 import type { ServerWebSocket } from 'bun';
-import type { Engine } from '../../core/engine.ts';
+import type { RegistryAgnosticEngine } from '../../core/engine.ts';
 import type { PrometheusExporter } from '../../observability/metrics.ts';
 import type { AuthConfig } from '../authentication.ts';
 import { type WebSocketData } from '../json-rpc-websocket-runtime.ts';
 import type { OpenApiSecuritySchemeName } from '../openapi.ts';
 import type { ServerContext } from './context.ts';
 type ServerFetchOptions = {
-    engine: Engine;
+    engine: RegistryAgnosticEngine;
     prometheusExporter?: PrometheusExporter;
     discoveryInfo?: import('../discovery-info.ts').DiscoveryInfo;
     publicOrigin?: string;

package/dist/server/serve-internals.js

@@ -85,7 +85,7 @@ export function resolveNetworkConfig(options) {
   return { port, hostname, development, tlsOptions, serverOptions, serverMetricsCollector };
 }
 export function buildServerContext(options, serverMetricsCollector) {
-  const workerRegistry = new WorkerRegistry(options.routingPolicy !== void 0 ? { policy: options.routingPolicy } : void 0), taskQueue = new TaskQueue(options.schedulingPolicy !== void 0 ? { schedulingPolicy: options.schedulingPolicy } : void 0), eventFeedBackend = createEngineEventFeedBackend(options.engine);
+  const workerRegistry = new WorkerRegistry(options.routingPolicy !== void 0 ? { policy: options.routingPolicy } : void 0), taskQueue = new TaskQueue(options.schedulingPolicy !== void 0 ? { schedulingPolicy: options.schedulingPolicy } : void 0), engine = options.engine, eventFeedBackend = createEngineEventFeedBackend(engine);
   return {
     registry: workerRegistry,
     taskQueue,
@@ -112,12 +112,12 @@ export function buildServerContext(options, serverMetricsCollector) {
     workflowEventFeed: createWorkflowEventFeed(eventFeedBackend),
     fleetEventFeed: createFleetEventFeed(options.engine.storage),
     activeJsonRpcSessions: new Set,
-    mcpSessionManager: createMcpSessionManager(options.engine),
+    mcpSessionManager: createMcpSessionManager(engine),
     authenticatorPromise: options.auth ? createAuthenticator(options.auth) : null,
     rateLimiter: options.rateLimit ? createRateLimiter(options.rateLimit) : null,
     visibilityPollMs: options.visibilityPollIntervalMs ?? 5000,
     workerReconnectGracePeriodMs: clampWorkerReconnectGracePeriod(options.workerReconnectGracePeriodMs),
-    payloadSizeMaxBytes: getEnginePayloadSizeMaxBytes(options.engine),
+    payloadSizeMaxBytes: getEnginePayloadSizeMaxBytes(engine),
     pendingWorkerRequeues: new Map,
     scanRunning: !1,
     processingOperations: new Set,

package/dist/server/task-queue.d.ts

@@ -14,21 +14,23 @@ export declare function resetLifoStarvationWarningForTesting(): void;
  * until a task arrives or the timeout expires.
  *
  * `serve()` owns the live instance and exposes it as
- * {@link WeftServer.taskQueue} for inspection. Prefer the `WeftServer` methods
- * (`dispatchTask`, `shutdownWorker`, etc.) over mutating the queue directly —
- * the type is re-exported so callers can name `server.taskQueue`, not as a
- * stable mutation surface.
+ * {@link WeftServer.taskQueue} for inspection. Direct `handleRequest()` hosts
+ * can construct an instance alongside a `WorkerRegistry` and inject both via
+ * `HandlerOptions`. Prefer the `WeftServer` methods (`dispatchTask`,
+ * `shutdownWorker`, etc.) over mutating a server-owned queue directly.
  *
  * @example
  * ```ts
- * import { serve, type TaskQueue } from '@lostgradient/weft/server';
+ * import { serve, TaskQueue } from '@lostgradient/weft/server';
  * import { Engine, MemoryStorage } from '@lostgradient/weft';
  *
  * await using engine = new Engine({ storage: new MemoryStorage() });
  * await using server = serve({ engine });
  *
  * const taskQueue: TaskQueue = server.taskQueue;
+ * const standaloneTaskQueue = new TaskQueue();
  * void taskQueue;
+ * standaloneTaskQueue[Symbol.dispose]();
  * ```
  */
 export declare class TaskQueue implements Disposable {

package/dist/server/workflow-event-feed.d.ts

@@ -1,7 +1,20 @@
 import type { WeftEventMap } from '../core/events.ts';
 /** Discriminator string carried on every feed envelope. */
 export type FeedEventKind = keyof WeftEventMap | 'workflow:checkpoint' | 'stream:chunk' | (string & {});
-/** Opaque cursor. Only `encodeCursor` / `decodeCursor` know the format. */
+/**
+ * Opaque cursor into a workflow or fleet event feed. Only `encodeCursor` /
+ * `decodeCursor` know the format — treat it as an opaque string, pass it back
+ * as `fromCursor` to resume a feed, and never parse it.
+ *
+ * @example
+ * ```ts
+ * import type { Cursor, EventEnvelope } from '@lostgradient/weft/server/handler';
+ *
+ * declare const envelope: EventEnvelope;
+ * const lastCursor: Cursor = envelope.cursor;
+ * void lastCursor;
+ * ```
+ */
 export type Cursor = string;
 /** Encode a non-negative integer sequence as an opaque cursor. */
 export declare function encodeCursor(sequence: number): Cursor;
@@ -11,6 +24,22 @@ export declare function encodeCursor(sequence: number): Cursor;
  */
 export declare function decodeCursor(cursor: Cursor): number | null;
 export type EventSelector = 'events' | 'tokens';
+/**
+ * A single committed record from a workflow's event feed — the `events`
+ * (durable log entries, e.g. `workflow:checkpoint`) or `tokens` (streamed
+ * output chunks) selector, distinguished by `selector`. Returned by
+ * `WorkflowEventFeed.replay()` / `WorkflowEventFeed.subscribe()`, and
+ * consumed directly by the `/v1/workflows/:id/events/sse` REST route.
+ *
+ * @example
+ * ```ts
+ * import type { EventEnvelope } from '@lostgradient/weft/server/handler';
+ *
+ * declare const envelope: EventEnvelope;
+ * console.log(envelope.selector); // 'events' | 'tokens'
+ * console.log(envelope.kind); // e.g. 'workflow:checkpoint'
+ * ```
+ */
 export type EventEnvelope = {
     readonly kind: FeedEventKind;
     readonly workflowId: string;
@@ -20,6 +49,26 @@ export type EventEnvelope = {
     readonly emittedAtMs: number;
     readonly payload: unknown;
 };
+/**
+ * The durable source a `WorkflowEventFeed` replays and subscribes against.
+ * Most callers never implement this directly — `createEngineEventFeedBackend()`
+ * builds the production, `Engine`-backed implementation. Implement it
+ * yourself only to back a feed with a non-`Engine` source (e.g. a test
+ * double).
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import {
+ *   createEngineEventFeedBackend,
+ *   type WorkflowEventFeedBackend,
+ * } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const backend: WorkflowEventFeedBackend = createEngineEventFeedBackend(engine);
+ * void backend;
+ * ```
+ */
 export type WorkflowEventFeedBackend = {
     replay(options: {
         workflowId: string;
@@ -29,6 +78,29 @@ export type WorkflowEventFeedBackend = {
     snapshotTailSequence(workflowId: string, selector: EventSelector): Promise<number>;
     subscribeLive(workflowId: string, selector: EventSelector, listener: (envelope: EventEnvelope) => void): () => void;
 };
+/**
+ * A per-workflow event feed: replay committed history from a cursor, then
+ * subscribe for live delivery. This is the shape of
+ * `HandlerOptions.workflowEventFeed` — build a real one with
+ * `createWorkflowEventFeed()` to drive `/v1/workflows/:id/events/sse`
+ * through `handleRequest()` without `serve()`.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import {
+ *   createEngineEventFeedBackend,
+ *   createWorkflowEventFeed,
+ *   type WorkflowEventFeed,
+ * } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const workflowEventFeed: WorkflowEventFeed = createWorkflowEventFeed(
+ *   createEngineEventFeedBackend(engine),
+ * );
+ * void workflowEventFeed;
+ * ```
+ */
 export type WorkflowEventFeed = {
     replay(options: {
         workflowId: string;
@@ -74,15 +146,32 @@ export type ReplayLiveSubscribeOptions<TEnvelope extends SequencedEventEnvelope>
     createReplayLimitError?: (count: number, limit: number) => unknown;
     onReplayComplete?: () => void;
 };
-export declare class ReplayWindowExceededError extends Error {
-    readonly count: number;
-    readonly limit: number;
-    constructor(count: number, limit: number);
-}
 export declare function createReplayLiveFeed<TEnvelope extends SequencedEventEnvelope>(backend: ReplayLiveFeedBackend<TEnvelope>, options?: WorkflowEventFeedOptions): ReplayLiveFeed<TEnvelope>;
+/**
+ * Build a `WorkflowEventFeed` over the given backend. Pass the result as
+ * `HandlerOptions.workflowEventFeed` to drive `/v1/workflows/:id/events/sse`
+ * through `handleRequest()` directly, without `serve()`. Call once and share
+ * the returned feed across every workflow and transport that needs it —
+ * `createWorkflowEventFeed()` itself holds no per-workflow state.
+ *
+ * @example
+ * ```ts
+ * import { Engine, MemoryStorage } from '@lostgradient/weft';
+ * import {
+ *   createEngineEventFeedBackend,
+ *   createWorkflowEventFeed,
+ *   handleRequest,
+ *   type HandlerOptions,
+ * } from '@lostgradient/weft/server/handler';
+ *
+ * const engine = new Engine({ storage: new MemoryStorage() });
+ * const workflowEventFeed = createWorkflowEventFeed(createEngineEventFeedBackend(engine));
+ * const options: HandlerOptions = { workflowEventFeed };
+ *
+ * async function handleWorkflowEventsSse(request: Request): Promise<Response> {
+ *   return handleRequest(request, engine, options);
+ * }
+ * void handleWorkflowEventsSse;
+ * ```
+ */
 export declare function createWorkflowEventFeed(backend: WorkflowEventFeedBackend, options?: WorkflowEventFeedOptions): WorkflowEventFeed;
-export type InMemoryEventBackend = WorkflowEventFeedBackend & {
-    append(envelope: EventEnvelope): Promise<void>;
-    emitLive(envelope: EventEnvelope): Promise<void>;
-};
-export declare function createInMemoryEventBackend(): InMemoryEventBackend;

package/dist/server/workflow-event-feed.js

@@ -1,3 +1,4 @@
+import { drainLive, replayUpTo, shouldDeliverEnvelope } from "./replay-live-feed-internals.js";
 const CURSOR_PATTERN = /^(?:-1|\d+)$/;
 export function encodeCursor(sequence) {
   if (!Number.isInteger(sequence) || sequence < 0)
@@ -18,17 +19,6 @@ function decodeCursorOrThrow(cursor) {
     throw Error("Invalid cursor");
   return sequence;
 }
-
-export class ReplayWindowExceededError extends Error {
-  count;
-  limit;
-  constructor(count, limit) {
-    super(`Replay window is ${count} events; maximum is ${limit}.`);
-    this.count = count;
-    this.limit = limit;
-    this.name = "ReplayWindowExceededError";
-  }
-}
 const DEFAULT_LIVE_BUFFER_SIZE = 1000;
 export function createReplayLiveFeed(backend, options) {
   const bufferSize = options?.liveBufferSize ?? DEFAULT_LIVE_BUFFER_SIZE;
@@ -138,132 +128,3 @@ export function createWorkflowEventFeed(backend, options) {
     dispose() {}
   };
 }
-async function* replayUpTo(backend, afterSequence, snapshot, signal, replayOptions) {
-  let replayCount = 0;
-  for await (const envelope of backend.replay({ afterSequence })) {
-    if (envelope.sequence > snapshot)
-      break;
-    if (signal?.aborted)
-      return;
-    if (!shouldDeliverEnvelope(envelope, replayOptions))
-      continue;
-    if (shouldCountReplayEnvelope(envelope, replayOptions)) {
-      replayCount += 1;
-      const replayLimit = replayOptions?.replayLimit;
-      if (replayLimit !== void 0 && replayCount > replayLimit)
-        throw createReplayLimitError(replayOptions, replayCount, replayLimit);
-    }
-    yield envelope;
-  }
-}
-function shouldDeliverEnvelope(envelope, replayOptions) {
-  return replayOptions?.filterEnvelope?.(envelope) ?? !0;
-}
-function shouldCountReplayEnvelope(envelope, replayOptions) {
-  return replayOptions?.countReplayEnvelope?.(envelope) ?? !0;
-}
-function createReplayLimitError(replayOptions, count, limit) {
-  return replayOptions?.createReplayLimitError?.(count, limit) ?? new ReplayWindowExceededError(count, limit);
-}
-function flushPendingBuffer(buffer, watermark) {
-  const batch = [];
-  let newWatermark = watermark, head = buffer.shift();
-  while (head !== void 0) {
-    if (head.sequence > newWatermark) {
-      batch.push(head);
-      newWatermark = head.sequence;
-    }
-    head = buffer.shift();
-  }
-  return { batch, newWatermark };
-}
-async function armAndWait(buffer, overflowed, signal, installWaker) {
-  const armed = new Promise((resolve) => {
-    installWaker(resolve);
-  });
-  if (buffer.length > 0 || overflowed() || signal?.aborted) {
-    installWaker(null);
-    return;
-  }
-  await armed;
-}
-async function* drainLive(buffer, snapshot, signal, overflowed, installWaker) {
-  let watermark = snapshot;
-  while (!0) {
-    if (signal?.aborted || overflowed())
-      break;
-    const { batch, newWatermark } = flushPendingBuffer(buffer, watermark);
-    watermark = newWatermark;
-    for (const envelope of batch) {
-      if (signal?.aborted || overflowed())
-        return;
-      yield envelope;
-    }
-    if (batch.length > 0)
-      continue;
-    await armAndWait(buffer, overflowed, signal, installWaker);
-  }
-}
-function bucketKey(workflowId, selector) {
-  return `${workflowId}:${selector}`;
-}
-export function createInMemoryEventBackend() {
-  const storage = new Map, listeners = new Map;
-  function fireLive(envelope) {
-    const set = listeners.get(bucketKey(envelope.workflowId, envelope.selector));
-    if (!set)
-      return;
-    for (const listener of set)
-      try {
-        listener(envelope);
-      } catch {}
-  }
-  return {
-    async* replay(options) {
-      const bucket = storage.get(bucketKey(options.workflowId, options.selector));
-      if (!bucket)
-        return;
-      const sorted = [...bucket].toSorted((a, b) => a.sequence - b.sequence);
-      for (const envelope of sorted)
-        if (envelope.sequence > options.afterSequence)
-          yield envelope;
-    },
-    async snapshotTailSequence(workflowId, selector) {
-      const bucket = storage.get(bucketKey(workflowId, selector));
-      if (!bucket || bucket.length === 0)
-        return -1;
-      let max = -1;
-      for (const envelope of bucket)
-        if (envelope.sequence > max)
-          max = envelope.sequence;
-      return max;
-    },
-    subscribeLive(workflowId, selector, listener) {
-      const k = bucketKey(workflowId, selector);
-      let set = listeners.get(k);
-      if (!set) {
-        set = new Set;
-        listeners.set(k, set);
-      }
-      set.add(listener);
-      return () => {
-        set?.delete(listener);
-        if (set && set.size === 0)
-          listeners.delete(k);
-      };
-    },
-    async append(envelope) {
-      const k = bucketKey(envelope.workflowId, envelope.selector);
-      let bucket = storage.get(k);
-      if (!bucket) {
-        bucket = [];
-        storage.set(k, bucket);
-      }
-      bucket.push(envelope);
-      fireLive(envelope);
-    },
-    async emitLive(envelope) {
-      fireLive(envelope);
-    }
-  };
-}

package/dist/service-worker/index.d.ts

@@ -6,7 +6,7 @@
  *
  * @module service-worker
  */
-import type { Engine } from '../core/engine';
+import type { RegistryAgnosticEngine } from '../core/engine';
 import type { ServiceWorkerScheduler } from './scheduler.ts';
 import type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEvent } from './shared.ts';
 export { ServiceWorkerScheduler } from './scheduler.ts';
@@ -36,7 +36,13 @@ export type { MinimalExtendableEvent, MinimalFetchEvent, MinimalPeriodicSyncEven
  * ```
  */
 export interface ServiceWorkerOptions {
-    engine: Engine;
+    /**
+     * The engine this handler delegates workflow requests to. Typed as
+     * {@link RegistryAgnosticEngine} (see its JSDoc) rather than the plain
+     * default `Engine`, so both `new Engine({ storage })` and
+     * `Engine.create({ workflows })` type-check here directly.
+     */
+    engine: RegistryAgnosticEngine;
     pathPrefix?: string;
 }
 /**