@opengeni/sdk 0.46.0 → 0.52.1

package/src/memory-slack-client.ts

@@ -0,0 +1,71 @@
+import type { OpenGeniClient as OpenGeniCoreClient } from "./client";
+import type {
+  MemorySlackPublication,
+  MemorySlackPublicationActionRequest,
+  MemorySlackPublicationConfiguration,
+  MemorySlackPublicationConfigurationResponse,
+  MemorySlackPublicationHistoryResponse,
+  SlackPublicationChannelListResponse,
+  UpdateMemorySlackPublicationConfigurationRequest,
+} from "./memory-slack-delivery";
+
+export type OpenGeniMemorySlackTransport = Pick<OpenGeniCoreClient, "requestJson">;
+
+/** Optional Memory-to-Slack API surface, isolated from the eager core client graph. */
+export class OpenGeniMemorySlackClient {
+  constructor(private readonly client: OpenGeniMemorySlackTransport) {}
+
+  async getMemorySlackPublicationConfiguration(
+    workspaceId: string,
+  ): Promise<MemorySlackPublicationConfigurationResponse> {
+    return await this.client.requestJson<MemorySlackPublicationConfigurationResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/configuration`,
+    );
+  }
+
+  async updateMemorySlackPublicationConfiguration(
+    workspaceId: string,
+    request: UpdateMemorySlackPublicationConfigurationRequest,
+  ): Promise<MemorySlackPublicationConfiguration> {
+    return await this.client.requestJson<MemorySlackPublicationConfiguration>(
+      "PUT",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/configuration`,
+      request,
+    );
+  }
+
+  async listMemorySlackPublicationChannels(
+    workspaceId: string,
+    connectionId: string,
+    cursor?: string,
+  ): Promise<SlackPublicationChannelListResponse> {
+    const query = new URLSearchParams({ connectionId });
+    if (cursor) query.set("cursor", cursor);
+    return await this.client.requestJson<SlackPublicationChannelListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/channels?${query}`,
+    );
+  }
+
+  async listMemorySlackPublications(
+    workspaceId: string,
+  ): Promise<MemorySlackPublicationHistoryResponse> {
+    return await this.client.requestJson<MemorySlackPublicationHistoryResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications`,
+    );
+  }
+
+  async actOnMemorySlackPublication(
+    workspaceId: string,
+    publicationId: string,
+    request: MemorySlackPublicationActionRequest,
+  ): Promise<MemorySlackPublication> {
+    return await this.client.requestJson<MemorySlackPublication>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/memory-slack-publications/${encodeURIComponent(publicationId)}/action`,
+      request,
+    );
+  }
+}

package/src/memory-slack-delivery.ts

@@ -0,0 +1,128 @@
+export type MemorySlackImportance = "major" | "normal" | "minor";
+export type MemorySlackRequestedMode = "auto" | "review" | "never";
+
+export type MemorySlackPublicationDistribution = {
+  importance: MemorySlackImportance;
+  audience: "workspace";
+  slackMode: MemorySlackRequestedMode;
+  shareSummary: string;
+};
+
+export type MemorySlackPublicationConfiguration = {
+  id: string;
+  workspaceId: string;
+  revision: number;
+  enabled: boolean;
+  connectionId: string | null;
+  slackTeamId: string | null;
+  slackChannelId: string | null;
+  slackChannelName: string | null;
+  autoImportances: MemorySlackImportance[];
+  reviewImportances: MemorySlackImportance[];
+  createdBySubjectId: string;
+  createdAt: string;
+};
+
+export type UpdateMemorySlackPublicationConfigurationRequest = {
+  expectedRevision: number;
+  enabled: boolean;
+  connectionId: string | null;
+  slackChannelId: string | null;
+  slackChannelName: string | null;
+  autoImportances: MemorySlackImportance[];
+  reviewImportances: MemorySlackImportance[];
+};
+
+export type MemorySlackPublicationConfigurationResponse = {
+  current: MemorySlackPublicationConfiguration | null;
+  history: MemorySlackPublicationConfiguration[];
+};
+
+export type MemorySlackPublicationState =
+  | "review_pending"
+  | "queued"
+  | "delivering"
+  | "retry_wait"
+  | "delivered"
+  | "rejected"
+  | "failed"
+  | "cancelled";
+
+export type MemorySlackPublicationReceiptKind =
+  | "enqueued"
+  | "review_approved"
+  | "review_rejected"
+  | "delivery_claimed"
+  | "retry_scheduled"
+  | "delivered"
+  | "failed"
+  | "cancelled"
+  | "manual_retry";
+
+export type MemorySlackPublicationReceipt = {
+  id: string;
+  publicationId: string;
+  sequence: number;
+  kind: MemorySlackPublicationReceiptKind;
+  state: MemorySlackPublicationState;
+  attemptNumber: number;
+  actorKind: "human" | "agent" | "service";
+  actorSubjectId: string;
+  operationId: string;
+  errorCode: string | null;
+  retryAt: string | null;
+  slackChannelId: string | null;
+  slackMessageTimestamp: string | null;
+  createdAt: string;
+};
+
+export type MemorySlackPublication = {
+  id: string;
+  workspaceId: string;
+  configurationRevision: number;
+  connectionId: string;
+  slackTeamId: string;
+  slackChannelId: string;
+  sourceType: "workspace_memory" | "durable_learning";
+  sourceId: string;
+  sourceVersion: string | null;
+  importance: MemorySlackImportance;
+  deliveryMode: "auto" | "review";
+  state: MemorySlackPublicationState;
+  summary: string;
+  sourceLabel: string;
+  authoritativePath: string | null;
+  initiatorKind: "human" | "agent" | "service";
+  initiatorSubjectId: string;
+  initiatingHumanSubjectId: string | null;
+  attemptCount: number;
+  retryAt: string | null;
+  lastErrorCode: string | null;
+  slackMessageTimestamp: string | null;
+  deliveredAt: string | null;
+  terminalAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  receipts: MemorySlackPublicationReceipt[];
+};
+
+export type MemorySlackPublicationHistoryResponse = {
+  publications: MemorySlackPublication[];
+  nextCursor: string | null;
+};
+
+export type MemorySlackPublicationActionRequest = {
+  action: "approve" | "reject" | "retry";
+  expectedState: MemorySlackPublicationState;
+};
+
+export type SlackPublicationChannel = {
+  id: string;
+  name: string | null;
+  isPrivate: boolean;
+};
+
+export type SlackPublicationChannelListResponse = {
+  channels: SlackPublicationChannel[];
+  nextCursor: string | null;
+};

package/src/memory-slack.ts

@@ -0,0 +1,19 @@
+/** Optional Memory-to-Slack API client; import this entry only where the capability is used. */
+export { OpenGeniMemorySlackClient } from "./memory-slack-client";
+export type { OpenGeniMemorySlackTransport } from "./memory-slack-client";
+export type {
+  MemorySlackImportance,
+  MemorySlackPublication,
+  MemorySlackPublicationActionRequest,
+  MemorySlackPublicationConfiguration,
+  MemorySlackPublicationConfigurationResponse,
+  MemorySlackPublicationDistribution,
+  MemorySlackPublicationHistoryResponse,
+  MemorySlackPublicationReceipt,
+  MemorySlackPublicationReceiptKind,
+  MemorySlackPublicationState,
+  MemorySlackRequestedMode,
+  SlackPublicationChannel,
+  SlackPublicationChannelListResponse,
+  UpdateMemorySlackPublicationConfigurationRequest,
+} from "./memory-slack-delivery";

package/src/retained-artifacts.ts

@@ -0,0 +1,326 @@
+import type {
+  GeneratedImageReceipt,
+  GeneratedVideoReceipt,
+  MediaGenerationResult,
+  RetainedArtifactReference,
+} from "./types";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISO_DATETIME_WITH_OFFSET =
+  /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+const WORKSPACE_PATH = /^\/v1\/workspaces\/([0-9a-f-]+)\/artifacts\/([0-9a-f-]+)\/content$/;
+const MAX_BYTES = 64 * 1024 * 1024;
+const MAX_VIDEO_BYTES = 512 * 1024 * 1024;
+const MAX_DIMENSION = 16_384;
+const MAX_PIXELS = 67_108_864;
+const MAX_RANGE_BYTES = 1024 * 1024;
+
+/** Zero-dependency validation for the SDK's permanent generated-image wire receipt. */
+export function parseRetainedGeneratedImageReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, GENERATED_IMAGE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "generated_image" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    !["image/png", "image/jpeg", "image/webp"].includes(String(artifact.contentType)) ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_BYTES) ||
+    typeof artifact.sha256 !== "string" ||
+    !SHA256.test(artifact.sha256) ||
+    typeof artifact.retainedAt !== "string" ||
+    artifact.retainedAt.length > 64 ||
+    !ISO_DATETIME_WITH_OFFSET.test(artifact.retainedAt) ||
+    !Number.isFinite(Date.parse(artifact.retainedAt)) ||
+    !recordWithKeys(artifact.dimensions, DIMENSION_KEYS) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const dimensions = artifact.dimensions as Record<string, unknown>;
+  if (
+    !safeIntegerBetween(dimensions.width, 1, MAX_DIMENSION) ||
+    !safeIntegerBetween(dimensions.height, 1, MAX_DIMENSION) ||
+    Number(dimensions.width) * Number(dimensions.height) > MAX_PIXELS
+  ) {
+    return null;
+  }
+  const retention = artifact.retention as Record<string, unknown>;
+  if (retention.policy !== "workspace_file" || retention.expiresAt !== null) return null;
+  const retrieval = artifact.retrieval as Record<string, unknown>;
+  if (
+    retrieval.method !== "GET" ||
+    retrieval.acceptRanges !== "bytes" ||
+    retrieval.maxRangeBytes !== MAX_RANGE_BYTES ||
+    typeof retrieval.path !== "string" ||
+    retrieval.path.length > 256
+  ) {
+    return null;
+  }
+  const match = WORKSPACE_PATH.exec(retrieval.path);
+  if (
+    !match ||
+    !UUID.test(match[1] ?? "") ||
+    match[2] !== artifact.artifactId ||
+    (expectedWorkspaceId !== undefined && match[1] !== expectedWorkspaceId)
+  ) {
+    return null;
+  }
+  return value as RetainedArtifactReference;
+}
+
+export function generatedImageSandboxPathMatches(
+  artifact: RetainedArtifactReference,
+  sandboxPath: unknown,
+): sandboxPath is string {
+  if (typeof sandboxPath !== "string") return false;
+  const extension =
+    artifact.contentType === "image/png"
+      ? "png"
+      : artifact.contentType === "image/jpeg"
+        ? "jpg"
+        : artifact.contentType === "image/webp"
+          ? "webp"
+          : null;
+  return (
+    extension !== null &&
+    sandboxPath ===
+      `/workspace/generated-images/generated-image-${artifact.artifactId}.${extension}`
+  );
+}
+
+/** Parse the complete closed generated-image tool result. */
+export function parseGeneratedImageReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): GeneratedImageReceipt | null {
+  if (typeof value === "string" && value.length <= 4_096) {
+    try {
+      return parseGeneratedImageReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, GENERATED_IMAGE_RECEIPT_KEYS)) return null;
+  if (value.type !== "generated_image") return null;
+  const artifact = parseRetainedGeneratedImageReference(value.artifact, expectedWorkspaceId);
+  if (!artifact || !generatedImageSandboxPathMatches(artifact, value.sandboxPath)) return null;
+  return { type: "generated_image", artifact, sandboxPath: value.sandboxPath };
+}
+
+/** Zero-dependency validation for a permanent generated-video reference. */
+export function parseRetainedGeneratedVideoReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, GENERATED_IMAGE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "generated_video" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    artifact.contentType !== "video/mp4" ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_VIDEO_BYTES) ||
+    typeof artifact.sha256 !== "string" ||
+    !SHA256.test(artifact.sha256) ||
+    typeof artifact.retainedAt !== "string" ||
+    artifact.retainedAt.length > 64 ||
+    !ISO_DATETIME_WITH_OFFSET.test(artifact.retainedAt) ||
+    !Number.isFinite(Date.parse(artifact.retainedAt)) ||
+    !recordWithKeys(artifact.dimensions, DIMENSION_KEYS) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const dimensions = artifact.dimensions as Record<string, unknown>;
+  if (
+    !safeIntegerBetween(dimensions.width, 1, 8_192) ||
+    !safeIntegerBetween(dimensions.height, 1, 8_192)
+  ) {
+    return null;
+  }
+  const retention = artifact.retention as Record<string, unknown>;
+  if (retention.policy !== "workspace_file" || retention.expiresAt !== null) return null;
+  const retrieval = artifact.retrieval as Record<string, unknown>;
+  if (
+    retrieval.method !== "GET" ||
+    retrieval.acceptRanges !== "bytes" ||
+    retrieval.maxRangeBytes !== MAX_RANGE_BYTES ||
+    typeof retrieval.path !== "string" ||
+    retrieval.path.length > 256
+  ) {
+    return null;
+  }
+  const match = WORKSPACE_PATH.exec(retrieval.path);
+  if (
+    !match ||
+    !UUID.test(match[1] ?? "") ||
+    match[2] !== artifact.artifactId ||
+    (expectedWorkspaceId !== undefined && match[1] !== expectedWorkspaceId)
+  ) {
+    return null;
+  }
+  return value as RetainedArtifactReference;
+}
+
+/** Parse the compact successful video result placed in model/timeline history. */
+export function parseGeneratedVideoReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): GeneratedVideoReceipt | null {
+  if (typeof value === "string" && value.length <= 8_192) {
+    try {
+      return parseGeneratedVideoReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, GENERATED_VIDEO_RECEIPT_KEYS)) return null;
+  if (
+    value.type !== "generated_video" ||
+    value.schemaVersion !== 1 ||
+    typeof value.operationId !== "string" ||
+    !UUID.test(value.operationId) ||
+    !recordWithKeys(value.video, GENERATED_VIDEO_FACT_KEYS)
+  ) {
+    return null;
+  }
+  const artifact = parseRetainedGeneratedVideoReference(value.artifact, expectedWorkspaceId);
+  const video = value.video as Record<string, unknown>;
+  if (
+    !artifact ||
+    typeof value.sandboxPath !== "string" ||
+    value.sandboxPath !==
+      `/workspace/generated-videos/generated-video-${artifact.artifactId}.mp4` ||
+    typeof video.durationSeconds !== "number" ||
+    !Number.isFinite(video.durationSeconds) ||
+    video.durationSeconds <= 0 ||
+    video.durationSeconds > 120 ||
+    video.width !== artifact.dimensions?.width ||
+    video.height !== artifact.dimensions?.height ||
+    typeof video.fps !== "number" ||
+    !Number.isFinite(video.fps) ||
+    video.fps <= 0 ||
+    video.fps > 120 ||
+    typeof video.hasAudio !== "boolean" ||
+    video.videoCodec !== "h264" ||
+    (video.audioCodec !== null && video.audioCodec !== "aac")
+  ) {
+    return null;
+  }
+  return value as GeneratedVideoReceipt;
+}
+
+/** Parse one closed terminal envelope; failures never fabricate an artifact. */
+export function parseMediaGenerationResult(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): MediaGenerationResult | null {
+  if (typeof value === "string" && value.length <= 12_000) {
+    try {
+      return parseMediaGenerationResult(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const result = value as Record<string, unknown>;
+  if (
+    result.type !== "media_generation_result" ||
+    result.schemaVersion !== 1 ||
+    typeof result.operationId !== "string" ||
+    !UUID.test(result.operationId)
+  ) {
+    return null;
+  }
+  if (result.status === "ready") {
+    if (!recordWithKeys(result, MEDIA_RESULT_READY_KEYS)) return null;
+    const receipt = parseGeneratedVideoReceipt(result.receipt, expectedWorkspaceId);
+    if (!receipt || receipt.operationId !== result.operationId) return null;
+    return value as MediaGenerationResult;
+  }
+  if (
+    !["provider_failed", "retention_failed", "cancelled_before_submit", "outcome_unknown"].includes(
+      String(result.status),
+    ) ||
+    !recordWithKeys(result, MEDIA_RESULT_FAILURE_KEYS) ||
+    typeof result.boundedPublicReason !== "string" ||
+    result.boundedPublicReason.length < 1 ||
+    result.boundedPublicReason.length > 1_000
+  ) {
+    return null;
+  }
+  return value as MediaGenerationResult;
+}
+
+const GENERATED_IMAGE_REFERENCE_KEYS = new Set([
+  "available",
+  "artifactId",
+  "kind",
+  "contentType",
+  "originalBytes",
+  "sha256",
+  "retainedAt",
+  "dimensions",
+  "retention",
+  "retrieval",
+]);
+const DIMENSION_KEYS = new Set(["width", "height"]);
+const RETENTION_KEYS = new Set(["policy", "expiresAt"]);
+const RETRIEVAL_KEYS = new Set(["method", "path", "acceptRanges", "maxRangeBytes"]);
+const GENERATED_IMAGE_RECEIPT_KEYS = new Set(["type", "artifact", "sandboxPath"]);
+const GENERATED_VIDEO_RECEIPT_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "operationId",
+  "artifact",
+  "video",
+  "sandboxPath",
+]);
+const GENERATED_VIDEO_FACT_KEYS = new Set([
+  "durationSeconds",
+  "width",
+  "height",
+  "fps",
+  "hasAudio",
+  "videoCodec",
+  "audioCodec",
+]);
+const MEDIA_RESULT_READY_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "status",
+  "operationId",
+  "receipt",
+]);
+const MEDIA_RESULT_FAILURE_KEYS = new Set([
+  "type",
+  "schemaVersion",
+  "status",
+  "operationId",
+  "boundedPublicReason",
+]);
+
+function recordWithKeys(
+  value: unknown,
+  allowed: ReadonlySet<string>,
+): value is Record<string, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === allowed.size &&
+    Object.keys(value).every((key) => allowed.has(key))
+  );
+}
+
+function safeIntegerBetween(value: unknown, min: number, max: number): boolean {
+  return Number.isSafeInteger(value) && Number(value) >= min && Number(value) <= max;
+}

package/src/stream.ts

@@ -29,13 +29,25 @@ export type StreamSessionEventsOptions = {
   reconnectDelayMs?: number;
   /** Backoff ceiling. Defaults to 10s. */
   maxReconnectDelayMs?: number;
+  /** Random backoff spread as a fraction of the delay. Defaults to 0.2. */
+  reconnectJitterRatio?: number;
   /**
    * Give up after this many consecutive failed reconnect attempts (i.e. N
    * reconnects = N+1 total open-stream calls). Defaults to unlimited.
    */
   maxReconnectAttempts?: number;
+  /**
+   * Notify the consumer as soon as the SSE response body is open. This callback
+   * is deliberately synchronous and non-blocking: use it to start projection
+   * reconciliation without delaying consumption of live event bytes.
+   */
+  onOpen?: (() => void) | undefined;
   /** Await authoritative client reconciliation before exposing `live`. */
   beforeLive?: (() => void | Promise<void>) | undefined;
+  /** Maximum reconciliation time before reconnecting. Defaults to 15s. */
+  beforeLiveTimeoutMs?: number;
+  /** Maximum time without any SSE bytes before reconnecting. Defaults to 45s. */
+  heartbeatTimeoutMs?: number;
   onStateChange?: (state: StreamConnectionState) => void;
 };
 
@@ -62,6 +74,9 @@ export async function* streamSessionEvents(
   const reconnect = options.reconnect ?? true;
   const baseDelayMs = options.reconnectDelayMs ?? 500;
   const maxDelayMs = options.maxReconnectDelayMs ?? 10_000;
+  const jitterRatio = options.reconnectJitterRatio ?? 0.2;
+  const beforeLiveTimeoutMs = options.beforeLiveTimeoutMs ?? 15_000;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? 45_000;
   const maxAttempts = options.maxReconnectAttempts ?? Number.POSITIVE_INFINITY;
   let cursor = options.after ?? 0;
   let failedAttempts = 0;
@@ -77,9 +92,16 @@ export async function* streamSessionEvents(
       everConnected = true;
       failedAttempts = 0;
       delayMs = baseDelayMs;
-      await options.beforeLive?.();
+      try {
+        options.onOpen?.();
+      } catch {
+        // A notification observer cannot own or interrupt the event transport.
+      }
+      await runBeforeLive(options.beforeLive, beforeLiveTimeoutMs, signal);
       options.onStateChange?.("live");
-      for await (const message of parseSseStream(body)) {
+      for await (const message of parseSseStream(
+        withStreamInactivityTimeout(body, heartbeatTimeoutMs, signal),
+      )) {
         // Re-check after every yield resumption: an abort from the consumer
         // must not let already-buffered events keep flowing.
         if (signal?.aborted) {
@@ -108,7 +130,7 @@ export async function* streamSessionEvents(
       // progress (servers legitimately cycle long SSE connections); pace
       // empty closes so a misbehaving server is not hammered in a hot loop.
       if (cursor === cursorAtOpen) {
-        await sleep(baseDelayMs, signal);
+        await sleep(jitteredDelay(baseDelayMs, jitterRatio), signal);
       }
       continue;
     } catch (error) {
@@ -125,11 +147,87 @@ export async function* streamSessionEvents(
         );
       }
     }
-    await sleep(delayMs, signal);
+    await sleep(jitteredDelay(delayMs, jitterRatio), signal);
     delayMs = Math.min(Math.max(delayMs * 2, baseDelayMs), maxDelayMs);
   }
 }
 
+export async function runBeforeLive(
+  beforeLive: (() => void | Promise<void>) | undefined,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): Promise<void> {
+  if (!beforeLive) return;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let abortListener: (() => void) | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(
+      () => reject(new TypeError(`stream reconciliation timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    if (signal) {
+      abortListener = () => reject(new DOMException("Aborted", "AbortError"));
+      signal.addEventListener("abort", abortListener, { once: true });
+    }
+  });
+  try {
+    await Promise.race([Promise.resolve().then(beforeLive), timeout]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+  }
+}
+
+export function jitteredDelay(delayMs: number, ratio: number): number {
+  if (delayMs <= 0 || ratio <= 0) return delayMs;
+  const boundedRatio = Math.min(ratio, 1);
+  const spread = delayMs * boundedRatio;
+  return Math.max(0, delayMs - spread + Math.random() * spread * 2);
+}
+
+export function withStreamInactivityTimeout(
+  stream: ReadableStream<Uint8Array>,
+  timeoutMs: number,
+  signal: AbortSignal | undefined,
+): ReadableStream<Uint8Array> {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+    throw new RangeError("stream heartbeat timeout must be a positive safe integer");
+  }
+  const reader = stream.getReader();
+  return new ReadableStream<Uint8Array>({
+    pull: async (controller) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let abortListener: (() => void) | undefined;
+      try {
+        const result = await Promise.race([
+          reader.read(),
+          new Promise<never>((_resolve, reject) => {
+            timer = setTimeout(
+              () => reject(new TypeError(`event stream heartbeat timed out after ${timeoutMs}ms`)),
+              timeoutMs,
+            );
+            if (signal) {
+              abortListener = () => reject(new DOMException("Aborted", "AbortError"));
+              signal.addEventListener("abort", abortListener, { once: true });
+            }
+          }),
+        ]);
+        if (result.done) controller.close();
+        else controller.enqueue(result.value);
+      } catch (error) {
+        void reader.cancel(error).catch(() => {});
+        controller.error(error);
+      } finally {
+        if (timer !== undefined) clearTimeout(timer);
+        if (signal && abortListener) signal.removeEventListener("abort", abortListener);
+      }
+    },
+    cancel: async (reason) => {
+      await reader.cancel(reason);
+    },
+  });
+}
+
 /**
  * Yield the durable events with `fromExclusive < sequence <= toInclusive`,
  * in order. Sequences are contiguous, so every one of them must exist in the