@effect-uai/core 0.14.0 → 0.16.0

package/src/messenger/Messenger.ts

@@ -0,0 +1,293 @@
+import { Brand, Context, Data, Effect, type Option, type Scope, Stream } from "effect"
+import type { MediaSource } from "../domain/Media.js"
+import type * as MessengerError from "./MessengerError.js"
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/** Where messages go. Providers mint these per their own scheme; core treats them opaquely. */
+export type ChannelId = Brand.Branded<string, "ChannelId">
+export const ChannelId = Brand.nominal<ChannelId>()
+
+/** One message inside a channel. Only a named message can be edited or reacted to. */
+export type MessageId = Brand.Branded<string, "MessageId">
+export const MessageId = Brand.nominal<MessageId>()
+
+/** The human (or bot) an event came from. */
+export type UserId = Brand.Branded<string, "UserId">
+export const UserId = Brand.nominal<UserId>()
+
+/** A sub-conversation inside a channel, where the platform has one. Opaque, provider-minted. */
+export type ThreadId = Brand.Branded<string, "ThreadId">
+export const ThreadId = Brand.nominal<ThreadId>()
+
+/**
+ * Where a conversation happens. `thread` is provider-interpreted: a Slack
+ * `thread_ts`, a Telegram forum topic, unset on Discord (where a thread is
+ * its own channel).
+ */
+export type ConversationRef = {
+  readonly channel: ChannelId
+  readonly thread?: ThreadId
+}
+
+export type MessageRef = {
+  readonly conversation: ConversationRef
+  readonly id: MessageId
+}
+
+/** Stable key for a conversation. Index per-conversation state with it. */
+export const conversationKey = (ref: ConversationRef): string =>
+  ref.thread === undefined ? ref.channel : `${ref.channel}/${ref.thread}`
+
+// ---------------------------------------------------------------------------
+// Inbound
+// ---------------------------------------------------------------------------
+
+/**
+ * What the world says to the agent. `raw` is the untouched platform payload,
+ * for everything the shared shape drops.
+ *
+ * `addressed` is the rule recipes branch on: a DM, a mention of the bot, or
+ * a reply to one of its messages. Each adapter owns that decision (and hides
+ * Telegram privacy mode / Discord intents behind it), and delivers `text`
+ * with the bot's own mention stripped.
+ *
+ * `Reaction.emoji` is the platform's own spelling, the same one `react`
+ * accepts: unicode where the platform speaks unicode, a shortcode where it
+ * speaks shortcodes.
+ */
+export type InboundEvent = Data.TaggedEnum<{
+  Message: {
+    readonly conversation: ConversationRef
+    readonly id: MessageId
+    readonly author: UserId
+    readonly text: string
+    readonly addressed: boolean
+    readonly replyTo?: MessageId
+    readonly raw: unknown
+  }
+  Reaction: {
+    readonly conversation: ConversationRef
+    readonly message: MessageId
+    readonly emoji: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+  Command: {
+    readonly conversation: ConversationRef
+    readonly name: string
+    readonly args: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+  Action: {
+    readonly conversation: ConversationRef
+    readonly actionId: string
+    readonly value?: string
+    readonly author: UserId
+    readonly raw: unknown
+  }
+}>
+
+export const InboundEvent = Data.taggedEnum<InboundEvent>()
+
+// ---------------------------------------------------------------------------
+// Outbound
+// ---------------------------------------------------------------------------
+
+/**
+ * What the agent says. `Text` is sent verbatim: each provider layer says
+ * which markup it expects (Telegram HTML, Slack markdown), and the prompt is
+ * where that gets decided. Nothing here converts. `Media` reuses the core
+ * {@link MediaSource}, so a URL, base64 or raw bytes all work; the adapter
+ * routes on `mimeType` (`image/*` to a photo endpoint, `audio/*` to an audio
+ * one, everything else to a file upload), which is why a URL source without
+ * a `mimeType` goes as a plain file. `Raw` bypasses the shape entirely and
+ * reaches the platform as-is: the escape hatch for buttons, cards and
+ * everything the verbs do not unify.
+ */
+export type OutboundBody = Data.TaggedEnum<{
+  Text: { readonly text: string }
+  Media: {
+    readonly media: MediaSource
+    readonly caption?: string
+    readonly filename?: string
+  }
+  Raw: { readonly payload: unknown }
+}>
+
+export const OutboundBody = Data.taggedEnum<OutboundBody>()
+
+/**
+ * A body plus the envelope fields true of any message. `replyTo` is ignored
+ * for a `Raw` body, which names its own wire fields.
+ */
+export type Outbound = {
+  readonly body: OutboundBody
+  readonly replyTo?: MessageId
+}
+
+export type OutboundOptions = { readonly replyTo?: MessageId }
+
+const envelope = (body: OutboundBody, options?: OutboundOptions): Outbound => ({
+  body,
+  ...(options?.replyTo !== undefined && { replyTo: options.replyTo }),
+})
+
+/** Text message. The overwhelmingly common case: `post(text("hi"))`. */
+export const text = (body: string, options?: OutboundOptions): Outbound =>
+  envelope(OutboundBody.Text({ text: body }), options)
+
+/** Media message. `caption` and `filename` describe the media, not the envelope. */
+export const media = (
+  source: MediaSource,
+  options?: OutboundOptions & { readonly caption?: string; readonly filename?: string },
+): Outbound =>
+  envelope(
+    OutboundBody.Media({
+      media: source,
+      ...(options?.caption !== undefined && { caption: options.caption }),
+      ...(options?.filename !== undefined && { filename: options.filename }),
+    }),
+    options,
+  )
+
+/** Platform payload, passed through untouched. */
+export const raw = (payload: unknown): Outbound => ({ body: OutboundBody.Raw({ payload }) })
+
+// ---------------------------------------------------------------------------
+// Ambient conversation targeting
+// ---------------------------------------------------------------------------
+
+/**
+ * The conversation the outbound verbs target. A tag with no default, so
+ * posting outside an established conversation is a compile error. Deep code
+ * (a tool posting progress, an approval resolver) inherits it rather than
+ * threading a ref down.
+ */
+export class CurrentConversation extends Context.Service<CurrentConversation, ConversationRef>()(
+  "@betalyra/effect-uai/Messenger/CurrentConversation",
+) {}
+
+/** Run `effect` against `ref`. Wrap a conversation fiber once; every nested post lands. */
+export const inConversation =
+  (ref: ConversationRef) =>
+  <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, CurrentConversation>> =>
+    Effect.provideService(effect, CurrentConversation, ref)
+
+// ---------------------------------------------------------------------------
+// Service definition
+// ---------------------------------------------------------------------------
+
+/** Envelope of a streamed reply. `replyTo` lands on the first message it posts. */
+export type StreamOptions = OutboundOptions
+
+/** Platform ceilings, so recipes can see them before composing a message. */
+export type MessengerLimits = {
+  /** Longest single text message. */
+  readonly maxText: number
+  /** Longest caption on a media message. */
+  readonly maxCaption: number
+}
+
+/**
+ * Cross-platform messaging: one inbound stream, five outbound verbs.
+ *
+ * `events` is single-consumer and provider-owned. The connection opens when
+ * the layer is built and closes with its scope, so there is no connect /
+ * disconnect here, and reconnects, acks and callback answering all happen
+ * below this line.
+ *
+ * `post`, `typing` and `stream` target the ambient
+ * {@link CurrentConversation}; `edit` and `react` name a message outright.
+ */
+export type MessengerService = {
+  readonly events: Stream.Stream<InboundEvent, MessengerError.MessengerError>
+
+  /** Text past `limits.maxText` goes out as several messages; the id is the last. */
+  readonly post: (
+    msg: Outbound,
+  ) => Effect.Effect<MessageId, MessengerError.MessengerError, CurrentConversation>
+
+  readonly edit: (
+    msg: MessageRef,
+    next: Outbound,
+  ) => Effect.Effect<void, MessengerError.MessengerError>
+
+  /**
+   * `emoji` in the platform's own spelling, as its `Reaction` events deliver
+   * it. Nothing is translated; one the platform rejects fails
+   * `MessengerUnsupported`.
+   */
+  readonly react: (
+    msg: MessageRef,
+    emoji: string,
+  ) => Effect.Effect<void, MessengerError.MessengerError>
+
+  /** Activity indicator, kept alive by the adapter until the scope closes. */
+  readonly typing: Effect.Effect<
+    void,
+    MessengerError.MessengerError,
+    CurrentConversation | Scope.Scope
+  >
+
+  /**
+   * Progressive delivery of a text stream; the mechanism is the adapter's.
+   * The id is the last message posted, `None` when the stream had no text.
+   */
+  readonly stream: <E, R>(
+    deltas: Stream.Stream<string, E, R>,
+    options?: StreamOptions,
+  ) => Effect.Effect<
+    Option.Option<MessageId>,
+    MessengerError.MessengerError | E,
+    R | CurrentConversation
+  >
+
+  readonly limits: MessengerLimits
+}
+
+export class Messenger extends Context.Service<Messenger, MessengerService>()(
+  "@betalyra/effect-uai/Messenger",
+) {}
+
+// ---------------------------------------------------------------------------
+// Free helpers
+// ---------------------------------------------------------------------------
+
+export const events: Stream.Stream<InboundEvent, MessengerError.MessengerError, Messenger> =
+  Stream.unwrap(Effect.map(Messenger, (m) => m.events))
+
+export const post = (
+  msg: Outbound,
+): Effect.Effect<MessageId, MessengerError.MessengerError, Messenger | CurrentConversation> =>
+  Effect.flatMap(Messenger, (m) => m.post(msg))
+
+export const edit = (
+  msg: MessageRef,
+  next: Outbound,
+): Effect.Effect<void, MessengerError.MessengerError, Messenger> =>
+  Effect.flatMap(Messenger, (m) => m.edit(msg, next))
+
+export const react = (
+  msg: MessageRef,
+  emoji: string,
+): Effect.Effect<void, MessengerError.MessengerError, Messenger> =>
+  Effect.flatMap(Messenger, (m) => m.react(msg, emoji))
+
+export const typing: Effect.Effect<
+  void,
+  MessengerError.MessengerError,
+  Messenger | CurrentConversation | Scope.Scope
+> = Effect.flatMap(Messenger, (m) => m.typing)
+
+export const stream = <E, R>(
+  deltas: Stream.Stream<string, E, R>,
+  options?: StreamOptions,
+): Effect.Effect<
+  Option.Option<MessageId>,
+  MessengerError.MessengerError | E,
+  R | Messenger | CurrentConversation
+> => Effect.flatMap(Messenger, (m) => m.stream(deltas, options))

package/src/messenger/MessengerAdapter.test.ts

@@ -0,0 +1,179 @@
+import { describe, it } from "@effect/vitest"
+import { Array as Arr, Duration, Effect, Option, Result, Stream } from "effect"
+import { TestClock } from "effect/testing"
+import { expect } from "vitest"
+import * as MockMessenger from "../testing/MockMessenger.js"
+import {
+  ChannelId,
+  type ConversationRef,
+  MessageId,
+  type Outbound,
+  type StreamOptions,
+  inConversation,
+} from "./Messenger.js"
+import { type StreamViaEditsOptions, splitForLimit } from "./MessengerAdapter.js"
+import { MessengerRateLimited } from "./MessengerError.js"
+
+const here: ConversationRef = { channel: ChannelId("c1") }
+
+const bodyOf = (msg: Outbound): string => (msg.body._tag === "Text" ? msg.body.text : "")
+
+const posts = (calls: ReadonlyArray<MockMessenger.Call>) =>
+  Arr.filterMap(calls, (c) =>
+    c._tag === "Post" ? Result.succeed(bodyOf(c.message)) : Result.failVoid,
+  )
+
+const edits = (calls: ReadonlyArray<MockMessenger.Call>) =>
+  Arr.filterMap(calls, (c) =>
+    c._tag === "Edit" ? Result.succeed(bodyOf(c.next)) : Result.failVoid,
+  )
+
+/** Run `deltas` through the mock's `stream` and hand back the call log. */
+const streamed = (
+  deltas: ReadonlyArray<string>,
+  script: MockMessenger.MockMessengerScript = {},
+  streamOptions?: StreamOptions,
+) =>
+  Effect.gen(function* () {
+    const { service, recorder } = MockMessenger.make(script)
+    const id = yield* service.stream(Stream.fromIterable(deltas), streamOptions)
+    const { calls } = yield* recorder
+    return { id, calls }
+  }).pipe(inConversation(here))
+
+const options = (o: StreamViaEditsOptions): MockMessenger.MockMessengerScript => ({
+  streamOptions: o,
+})
+
+// ---------------------------------------------------------------------------
+// splitForLimit
+// ---------------------------------------------------------------------------
+
+describe("splitForLimit", () => {
+  it("prefers a paragraph break, then a line, then a word", () => {
+    expect(splitForLimit("aaa\n\nbbb ccc", 8)).toEqual(["aaa", "bbb ccc"])
+    expect(splitForLimit("aaa\nbbbb ccc", 8)).toEqual(["aaa", "bbbb ccc"])
+    expect(splitForLimit("aaaa bbbb ccc", 9)).toEqual(["aaaa", "bbbb ccc"])
+  })
+
+  it("hard-cuts a run with no boundary inside the limit", () => {
+    expect(splitForLimit("aaaaaaaaaa", 4)).toEqual(["aaaa", "aaaa", "aa"])
+  })
+})
+
+// ---------------------------------------------------------------------------
+// streamViaEdits
+// ---------------------------------------------------------------------------
+
+describe("streamViaEdits", () => {
+  // TestClock keeps wall time frozen, so the `every` gate never opens and
+  // every delta after the first coalesces into the final flush.
+  it.effect("coalesces deltas arriving inside the `every` window", () =>
+    Effect.gen(function* () {
+      const { calls } = yield* streamed(["Hel", "lo ", "the", "re!"])
+
+      expect(posts(calls)).toEqual(["Hel"])
+      expect(edits(calls)).toEqual(["Hello there!"])
+    }),
+  )
+
+  it.effect("waits for `minChars` of growth before spending an edit", () =>
+    Effect.gen(function* () {
+      const { calls } = yield* streamed(
+        ["aaaa", "bbbb", "cccc", "dddd", "eeee", "ffff"],
+        options({ every: 0, minChars: 10 }),
+      )
+
+      // Edits land at 16 chars (12 of growth) and again on the final flush.
+      expect(posts(calls)).toEqual(["aaaa"])
+      expect(edits(calls).map((t) => t.length)).toEqual([16, 24])
+    }),
+  )
+
+  it.effect("skips the final flush when the message already shows the text", () =>
+    Effect.gen(function* () {
+      const { calls } = yield* streamed(
+        ["aaaaa", "bbbbb", "ccccc"],
+        options({ every: 0, minChars: 10 }),
+      )
+
+      // The third delta opens the growth gate, so the tail is already sent.
+      expect(edits(calls)).toEqual(["aaaaabbbbbccccc"])
+    }),
+  )
+
+  it.effect("rolls over to a new message past maxText", () =>
+    Effect.gen(function* () {
+      const { id, calls } = yield* streamed(["aaaa bbbb cccc dddd"], {
+        limits: { maxText: 10, maxCaption: 10 },
+      })
+
+      // Cut on the word boundary, not mid-word, and the id is the last message.
+      expect(posts(calls)).toEqual(["aaaa bbbb", "cccc dddd"])
+      expect(edits(calls)).toEqual([])
+      expect(id).toEqual(Option.some(MessageId("m2")))
+    }),
+  )
+
+  it.effect("quotes the question on the first message only, never on a rollover", () =>
+    Effect.gen(function* () {
+      const { calls } = yield* streamed(
+        ["aaaa bbbb cccc dddd"],
+        { limits: { maxText: 10, maxCaption: 10 } },
+        { replyTo: MessageId("q1") },
+      )
+
+      const replies = Arr.filterMap(calls, (c) =>
+        c._tag === "Post" ? Result.succeed(c.message.replyTo) : Result.failVoid,
+      )
+      expect(replies).toEqual([MessageId("q1"), undefined])
+    }),
+  )
+
+  it.effect("posts nothing for a stream with no text", () =>
+    Effect.gen(function* () {
+      const { id, calls } = yield* streamed(["", ""])
+
+      expect(calls).toEqual([])
+      expect(id).toEqual(Option.none())
+    }),
+  )
+
+  // A model opening a tool-calling turn with a newline, which every platform
+  // rejects as an empty message.
+  it.effect("treats whitespace-only deltas as no text at all", () =>
+    Effect.gen(function* () {
+      const { id, calls } = yield* streamed(["\n", "  ", "\n\n"])
+
+      expect(calls).toEqual([])
+      expect(id).toEqual(Option.none())
+    }),
+  )
+
+  it.live("waits out a rate limit and re-sends the same edit", () =>
+    Effect.gen(function* () {
+      const limited = new MessengerRateLimited({
+        provider: "mock",
+        retryAfter: Duration.millis(10),
+      })
+      const { calls } = yield* streamed(["abc", "defghij"], {
+        ...options({ every: 0, minChars: 1 }),
+        failures: [undefined, limited],
+      })
+
+      expect(posts(calls)).toEqual(["abc"])
+      expect(edits(calls)).toEqual(["abcdefghij", "abcdefghij"])
+    }),
+  )
+
+  it.effect("gives up once the rate-limit budget is spent", () =>
+    Effect.gen(function* () {
+      const limited = new MessengerRateLimited({ provider: "mock", retryAfter: Duration.zero })
+      const failed = yield* Effect.flip(
+        streamed(["abc"], { ...options({ rateLimitRetries: 1 }), failures: [limited, limited] }),
+      )
+
+      expect(failed._tag).toBe("MessengerRateLimited")
+    }).pipe(TestClock.withLive),
+  )
+})

package/src/messenger/MessengerAdapter.ts

@@ -0,0 +1,189 @@
+/**
+ * What an adapter author needs and a recipe author never sees: text
+ * splitting at a platform ceiling, and post-then-edit progressive delivery
+ * for platforms without a native streaming API.
+ */
+import { Array as Arr, Clock, Data, Duration, Effect, Option, Schedule, Stream } from "effect"
+import {
+  CurrentConversation,
+  type MessageId,
+  type MessengerService,
+  type StreamOptions,
+  text,
+} from "./Messenger.js"
+import type * as MessengerError from "./MessengerError.js"
+
+// ---------------------------------------------------------------------------
+// Text splitting
+// ---------------------------------------------------------------------------
+
+// Paragraph break first, then line break, then space.
+const boundaries = ["\n\n", "\n", " "] as const
+
+/** Best split at or before `limit`; a hard cut only for an unbroken run. */
+const cutAt = (body: string, limit: number): readonly [head: string, rest: string] =>
+  body.length <= limit
+    ? [body, ""]
+    : Arr.findFirst(boundaries, (sep) =>
+        Option.map(
+          Option.liftPredicate(body.lastIndexOf(sep, limit - sep.length), (at) => at > 0),
+          (at) => [body.slice(0, at), body.slice(at + sep.length)] as const,
+        ),
+      ).pipe(Option.getOrElse(() => [body.slice(0, limit), body.slice(limit)] as const))
+
+/**
+ * Chunk `body` into pieces no longer than `limit`, breaking on paragraph,
+ * line, then word boundaries. Always yields at least one chunk, so callers
+ * have something to send even for empty input.
+ */
+export const splitForLimit = (body: string, limit: number): Arr.NonEmptyReadonlyArray<string> => {
+  const [head, rest] = cutAt(body, limit)
+  return rest.length === 0 ? [head] : [head, ...splitForLimit(rest, limit)]
+}
+
+// ---------------------------------------------------------------------------
+// streamViaEdits
+// ---------------------------------------------------------------------------
+
+/** The slice of a messenger that {@link streamViaEdits} drives. */
+export type EditableVerbs = Pick<MessengerService, "post" | "edit" | "limits">
+
+export type StreamViaEditsOptions = {
+  /** Minimum wall time between edits. Default 1 second. */
+  readonly every?: Duration.Input
+  /** Minimum growth since the last edit before spending another. Default 40. */
+  readonly minChars?: number
+  /** How often to honour a `MessengerRateLimited` before giving up. Default 3. */
+  readonly rateLimitRetries?: number
+}
+
+const isRateLimited = (e: MessengerError.MessengerError): boolean =>
+  e._tag === "MessengerRateLimited"
+
+// A retry schedule's input is the error, so the delay is the platform's own
+// `retry_after` rather than a guess. Bounded by `recurs`, so an unlucky call
+// eventually surfaces the rate limit instead of stalling behind it.
+const honourRetryAfter = (
+  times: number,
+): Schedule.Schedule<number, MessengerError.MessengerError> =>
+  Schedule.recurs(times).pipe(
+    Schedule.setInputType<MessengerError.MessengerError>(),
+    Schedule.modifyDelay(({ input }) =>
+      Effect.succeed(input._tag === "MessengerRateLimited" ? input.retryAfter : Duration.zero),
+    ),
+  )
+
+/**
+ * The message being filled: not on the platform yet, or posted and edited
+ * since. Only the first draft carries the reply; rollover drafts do not.
+ */
+type Progress = Data.TaggedEnum<{
+  Draft: { readonly pending: string; readonly envelope: StreamOptions }
+  Sent: {
+    readonly id: MessageId
+    /** Text the message shows now. Never resent unchanged. */
+    readonly sent: string
+    /** Text it should show, deltas included. */
+    readonly pending: string
+    readonly lastFlush: number
+  }
+}>
+
+const Progress = Data.taggedEnum<Progress>()
+
+type Sent = Data.TaggedEnum.Value<Progress, "Sent">
+
+const appended = (s: Progress, delta: string): Progress => ({
+  ...s,
+  pending: s.pending + delta,
+})
+
+/**
+ * Progressive delivery as post-then-edit, for adapters with no native
+ * streaming API. Coalesces deltas by time and growth, never resends
+ * unchanged text, waits out `MessengerRateLimited`, rolls over to a fresh
+ * message past `limits.maxText`, and always flushes the tail.
+ *
+ * The first chunk goes out as soon as any text arrives, so the message shows
+ * up immediately and fills in from there. A stream that produced no text
+ * posts nothing and yields `None`.
+ */
+export const streamViaEdits =
+  (verbs: EditableVerbs, options?: StreamViaEditsOptions): MessengerService["stream"] =>
+  (deltas, streamOptions = {}) =>
+    Effect.gen(function* () {
+      const every = Duration.toMillis(options?.every ?? "1 second")
+      const minChars = options?.minChars ?? 40
+      const schedule = honourRetryAfter(options?.rateLimitRetries ?? 3)
+      const conversation = yield* CurrentConversation
+
+      const patiently = <A, R2>(
+        effect: Effect.Effect<A, MessengerError.MessengerError, R2>,
+      ): Effect.Effect<A, MessengerError.MessengerError, R2> =>
+        Effect.retry(effect, { schedule, while: isRateLimited })
+
+      // Post a draft, edit a sent message, and skip an edit that would resend
+      // what the message already shows.
+      const deliver = (
+        s: Progress,
+        body: string,
+        now: number,
+      ): Effect.Effect<Sent, MessengerError.MessengerError, CurrentConversation> =>
+        Progress.$match(s, {
+          Draft: ({ pending, envelope }) =>
+            patiently(verbs.post(text(body, envelope))).pipe(
+              Effect.map((id) => Progress.Sent({ id, sent: body, pending, lastFlush: now })),
+            ),
+          Sent: (sent) =>
+            body === sent.sent
+              ? Effect.succeed(sent)
+              : patiently(verbs.edit({ conversation, id: sent.id }, text(body))).pipe(
+                  Effect.as(Progress.Sent({ ...sent, sent: body, lastFlush: now })),
+                ),
+        })
+
+      // Anything past the ceiling becomes the next message: finish the current
+      // one at a clean boundary, then start a draft on the remainder.
+      const rollover = (
+        s: Progress,
+        now: number,
+      ): Effect.Effect<Progress, MessengerError.MessengerError, CurrentConversation> => {
+        const [head, rest] = cutAt(s.pending, verbs.limits.maxText)
+        return rest.length === 0
+          ? Effect.succeed(s)
+          : deliver(s, head, now).pipe(
+              Effect.flatMap(() => rollover(Progress.Draft({ pending: rest, envelope: {} }), now)),
+            )
+      }
+
+      // A draft lands on its first real text; a sent message waits for both
+      // gates. Blank is not text: a model that opens a tool-calling turn with
+      // a newline would otherwise post it, and platforms reject a message
+      // that is only whitespace.
+      const due = (s: Progress, now: number): boolean =>
+        Progress.$match(s, {
+          Draft: ({ pending }) => pending.trim().length > 0,
+          Sent: ({ sent, pending, lastFlush }) =>
+            now - lastFlush >= every && pending.length - sent.length >= minChars,
+        })
+
+      const step = (before: Progress, delta: string) =>
+        Effect.gen(function* () {
+          const now = yield* Clock.currentTimeMillis
+          const s = yield* rollover(appended(before, delta), now)
+          if (!due(s, now)) return s
+          return yield* deliver(s, s.pending, now)
+        })
+
+      const folded = yield* Stream.runFoldEffect(
+        deltas,
+        () => Progress.Draft({ pending: "", envelope: streamOptions }),
+        step,
+      )
+      const now = yield* Clock.currentTimeMillis
+      const s = yield* rollover(folded, now)
+      // The tail always lands; a draft that never held text is nothing to send.
+      if (s._tag === "Draft" && s.pending.trim().length === 0) return Option.none()
+      const final = yield* deliver(s, s.pending, now)
+      return Option.some(final.id)
+    })