@lostgradient/weft 0.11.0 → 0.12.0

package/dist/server/operations/submit-review-decision.d.ts

@@ -5,6 +5,7 @@ declare const submitReviewDecisionInput: z.ZodObject<{
     decision: z.ZodOptional<z.ZodUnknown>;
     reviewer: z.ZodOptional<z.ZodUnknown>;
     feedback: z.ZodOptional<z.ZodUnknown>;
+    sectionDecisions: z.ZodOptional<z.ZodUnknown>;
     workflowId: z.ZodOptional<z.ZodUnknown>;
 }, z.core.$strip>;
 declare const submitReviewDecisionOutput: z.ZodObject<{
@@ -17,6 +18,7 @@ export declare const submitReviewDecisionOperation: import("../operation-catalog
     decision?: unknown;
     reviewer?: unknown;
     feedback?: unknown;
+    sectionDecisions?: unknown;
     workflowId?: unknown;
 }, {
     ok: true;

package/dist/server/operations/submit-review-decision.js

@@ -6,15 +6,28 @@ const VALID_DECISIONS = [
   "approved",
   "rejected",
   "needs-changes"
-], submitReviewDecisionInput = z.object({
+], sectionDecisionsSchema = z.record(z.string(), z.enum(["approved", "rejected"])), submitReviewDecisionInput = z.object({
   reviewId: z.string().min(1),
   decision: z.unknown().optional(),
   reviewer: z.unknown().optional(),
   feedback: z.unknown().optional(),
+  sectionDecisions: z.unknown().optional(),
   workflowId: z.unknown().optional()
 }), submitReviewDecisionOutput = z.object({
   ok: z.literal(!0)
 });
+function parseSectionDecisions(sectionDecisions) {
+  if (sectionDecisions === void 0)
+    return;
+  const parsed = sectionDecisionsSchema.safeParse(sectionDecisions);
+  if (!parsed.success)
+    throw {
+      code: "InvalidParams",
+      message: 'Field "sectionDecisions" must be a record mapping section names to "approved" or "rejected"',
+      data: { issues: [] }
+    };
+  return parsed.data;
+}
 function validateReviewDecisionInput(input) {
   if (typeof input.decision !== "string" || typeof input.reviewer !== "string")
     throw {
@@ -34,9 +47,11 @@ function validateReviewDecisionInput(input) {
       message: 'Field "feedback" must be a string when provided',
       data: { issues: [] }
     };
-  const { decision, reviewer } = input, reviewOptions = { decision, reviewer };
+  const sectionDecisions = parseSectionDecisions(input.sectionDecisions), decision = input.decision, reviewer = input.reviewer, reviewOptions = { decision, reviewer };
   if (typeof input.feedback === "string")
     reviewOptions.feedback = input.feedback;
+  if (sectionDecisions !== void 0)
+    reviewOptions.sectionDecisions = sectionDecisions;
   if (typeof input.workflowId === "string")
     reviewOptions.workflowId = input.workflowId;
   return { decision, reviewer, reviewOptions };
@@ -94,6 +109,7 @@ export const submitReviewDecisionRestBinding = {
     decision: { kind: "body-field", bodyField: "decision" },
     reviewer: { kind: "body-field", bodyField: "reviewer" },
     feedback: { kind: "body-field", bodyField: "feedback" },
+    sectionDecisions: { kind: "body-field", bodyField: "sectionDecisions" },
     workflowId: { kind: "body-field", bodyField: "workflowId" }
   },
   extractInput: async (request, pathParams, context) => {
@@ -107,6 +123,7 @@ export const submitReviewDecisionRestBinding = {
       decision: record.decision,
       reviewer: record.reviewer,
       feedback: record.feedback,
+      sectionDecisions: record.sectionDecisions,
       workflowId: record.workflowId
     };
   },

package/dist/server/replay-live-feed-internals.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Private replay/live-drain algorithm shared by every `createReplayLiveFeed()`
+ * instance (`workflow-event-feed.ts`'s per-workflow feed and
+ * `fleet-event-feed.ts`'s fleet-wide feed). Split out of
+ * `workflow-event-feed.ts` purely to keep that file under the repository's
+ * implementation-file line limit — nothing here is public API.
+ *
+ * @module server/replay-live-feed-internals
+ */
+import type { ReplayLiveFeedBackend, ReplayLiveSubscribeOptions, SequencedEventEnvelope } from './workflow-event-feed.ts';
+/** Thrown when a replay window exceeds the caller's configured limit. */
+export declare class ReplayWindowExceededError extends Error {
+    readonly count: number;
+    readonly limit: number;
+    constructor(count: number, limit: number);
+}
+export declare function replayUpTo<TEnvelope extends SequencedEventEnvelope>(backend: ReplayLiveFeedBackend<TEnvelope>, afterSequence: number, snapshot: number, signal: AbortSignal | undefined, replayOptions: ReplayLiveSubscribeOptions<TEnvelope> | undefined): AsyncIterable<TEnvelope>;
+export declare function shouldDeliverEnvelope<TEnvelope extends SequencedEventEnvelope>(envelope: TEnvelope, replayOptions: ReplayLiveSubscribeOptions<TEnvelope> | undefined): boolean;
+export declare function drainLive<TEnvelope extends SequencedEventEnvelope>(buffer: TEnvelope[], snapshot: number, signal: AbortSignal | undefined, overflowed: () => boolean, installWaker: (fn: (() => void) | null) => void): AsyncIterable<TEnvelope>;

package/dist/server/replay-live-feed-internals.js

@@ -0,0 +1,76 @@
+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";
+  }
+}
+export 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;
+  }
+}
+export 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;
+}
+export 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);
+  }
+}

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/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;
 }
 /**