@effect-uai/core 0.14.0 → 0.15.0

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)
+    })

package/src/messenger/MessengerError.ts

@@ -0,0 +1,67 @@
+import { Data, type Duration, Match } from "effect"
+
+// `reason` is required wherever one exists: the platform always says
+// something, and an adapter raising `Unsupported` knows why it did.
+
+/** Transport never came up: bad token, rejected handshake. Raised at layer build. */
+export class MessengerConnectFailed extends Data.TaggedError("MessengerConnectFailed")<{
+  provider: string
+  reason: string
+  raw: unknown
+}> {}
+
+/**
+ * Inbound transport ended for good (reconnect budget spent, fatal close).
+ * Routine reconnects stay inside the adapter and never surface here.
+ */
+export class MessengerTransportClosed extends Data.TaggedError("MessengerTransportClosed")<{
+  provider: string
+  reason: string
+  raw?: unknown
+}> {}
+
+/** Which verb was rejected. */
+export type MessengerOperation = "post" | "edit" | "react" | "typing"
+
+/** An outbound verb was rejected: permission, unknown chat, text too long, no-op edit. */
+export class MessengerRequestFailed extends Data.TaggedError("MessengerRequestFailed")<{
+  provider: string
+  operation: MessengerOperation
+  reason: string
+  raw: unknown
+}> {}
+
+/**
+ * Slow down, for this long. Typed rather than retried blindly so callers -
+ * `streamViaEdits` above all - decide whether waiting is still worth it.
+ */
+export class MessengerRateLimited extends Data.TaggedError("MessengerRateLimited")<{
+  provider: string
+  retryAfter: Duration.Duration
+  raw?: unknown
+}> {}
+
+/** The platform cannot express this at all: off-set reaction emoji, edits on WhatsApp. */
+export class MessengerUnsupported extends Data.TaggedError("MessengerUnsupported")<{
+  provider: string
+  capability: string
+  reason: string
+}> {}
+
+export type MessengerError =
+  | MessengerConnectFailed
+  | MessengerTransportClosed
+  | MessengerRequestFailed
+  | MessengerRateLimited
+  | MessengerUnsupported
+
+/** Human-readable description for logs. Prose, not a contract; branch on `_tag`. */
+export const describe: (e: MessengerError) => string = Match.type<MessengerError>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    MessengerConnectFailed: (e) => `the messenger could not connect: ${e.reason}`,
+    MessengerTransportClosed: (e) => `the messenger connection closed: ${e.reason}`,
+    MessengerRequestFailed: (e) => `the ${e.operation} was rejected: ${e.reason}`,
+    MessengerRateLimited: () => "the messenger is rate limited",
+    MessengerUnsupported: (e) => `this messenger does not support ${e.capability}: ${e.reason}`,
+  }),
+)

package/src/testing/MockMessenger.ts

@@ -0,0 +1,147 @@
+import { Array as Arr, Data, Effect, Layer, Option, Ref, Stream } from "effect"
+import {
+  type ConversationRef,
+  CurrentConversation,
+  type InboundEvent,
+  MessageId,
+  type MessageRef,
+  Messenger,
+  type MessengerLimits,
+  type MessengerService,
+  type Outbound,
+} from "../messenger/Messenger.js"
+import {
+  type StreamViaEditsOptions,
+  splitForLimit,
+  streamViaEdits,
+} from "../messenger/MessengerAdapter.js"
+import * as MessengerError from "../messenger/MessengerError.js"
+
+// ---------------------------------------------------------------------------
+// Call log
+// ---------------------------------------------------------------------------
+
+/**
+ * One entry per outbound call. `Post` is logged once even when the text was
+ * long enough to split, so a caller that rolled over on its own is
+ * distinguishable from one that leaned on `post` to do it.
+ */
+export type Call = Data.TaggedEnum<{
+  Post: { readonly conversation: ConversationRef; readonly message: Outbound }
+  Edit: { readonly message: MessageRef; readonly next: Outbound }
+  React: { readonly message: MessageRef; readonly emoji: string }
+  TypingStart: { readonly conversation: ConversationRef }
+  TypingStop: { readonly conversation: ConversationRef }
+}>
+
+export const Call = Data.taggedEnum<Call>()
+
+export type MockMessengerRecorder = {
+  readonly calls: ReadonlyArray<Call>
+}
+
+// ---------------------------------------------------------------------------
+// Script
+// ---------------------------------------------------------------------------
+
+export type MockMessengerScript = {
+  /** Inbound events to replay. Empty by default. */
+  readonly events?: Stream.Stream<InboundEvent, MessengerError.MessengerError>
+  readonly limits?: MessengerLimits
+  /**
+   * Failures handed back one per `post` / `edit` call, in order; `undefined`
+   * entries succeed, and everything past the end succeeds.
+   */
+  readonly failures?: ReadonlyArray<MessengerError.MessengerError | undefined>
+  /** Passed through to `streamViaEdits`, which backs `stream`. */
+  readonly streamOptions?: StreamViaEditsOptions
+}
+
+const defaultLimits: MessengerLimits = { maxText: 4096, maxCaption: 1024 }
+
+const bodyText = (msg: Outbound): Option.Option<string> =>
+  msg.body._tag === "Text" ? Option.some(msg.body.text) : Option.none()
+
+// ---------------------------------------------------------------------------
+// Service builder
+// ---------------------------------------------------------------------------
+
+const buildService = (
+  script: MockMessengerScript,
+  record: (call: Call) => Effect.Effect<void>,
+  cursor: Ref.Ref<number>,
+  minted: Ref.Ref<number>,
+): MessengerService => {
+  const limits = script.limits ?? defaultLimits
+
+  const nextFailure = Ref.getAndUpdate(cursor, (n) => n + 1).pipe(
+    Effect.flatMap((i) =>
+      Option.match(Option.fromNullishOr((script.failures ?? [])[i]), {
+        onNone: () => Effect.void,
+        onSome: Effect.fail<MessengerError.MessengerError>,
+      }),
+    ),
+  )
+
+  const mint = Ref.updateAndGet(minted, (n) => n + 1).pipe(Effect.map((n) => MessageId(`m${n}`)))
+
+  const post: MessengerService["post"] = (msg) =>
+    Effect.gen(function* () {
+      const conversation = yield* CurrentConversation
+      yield* record(Call.Post({ conversation, message: msg }))
+      yield* nextFailure
+      // One id per chunk, mirroring an adapter that splits at the ceiling.
+      const chunks = Option.match(bodyText(msg), {
+        onNone: () => 1,
+        onSome: (t) => splitForLimit(t, limits.maxText).length,
+      })
+      return yield* Effect.map(
+        Effect.forEach(Arr.range(1, chunks), () => mint),
+        Arr.lastNonEmpty,
+      )
+    })
+
+  const edit: MessengerService["edit"] = (msg, next) =>
+    record(Call.Edit({ message: msg, next })).pipe(Effect.andThen(nextFailure))
+
+  return {
+    events: script.events ?? Stream.empty,
+    post,
+    edit,
+    react: (msg, emoji) => record(Call.React({ message: msg, emoji })),
+    typing: Effect.gen(function* () {
+      const conversation = yield* CurrentConversation
+      yield* record(Call.TypingStart({ conversation }))
+      yield* Effect.addFinalizer(() => record(Call.TypingStop({ conversation })))
+    }),
+    stream: streamViaEdits({ post, edit, limits }, script.streamOptions),
+    limits,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const makeUnsafe = (script: MockMessengerScript) => {
+  const calls = Ref.makeUnsafe<ReadonlyArray<Call>>([])
+  const service = buildService(
+    script,
+    (call) => Ref.update(calls, Arr.append(call)),
+    Ref.makeUnsafe(0),
+    Ref.makeUnsafe(0),
+  )
+  return {
+    service,
+    recorder: Ref.get(calls).pipe(Effect.map((c): MockMessengerRecorder => ({ calls: c }))),
+  }
+}
+
+/** Layer registering the mock against the `Messenger` tag, plus its recorder. */
+export const layer = (script: MockMessengerScript = {}) => {
+  const { service, recorder } = makeUnsafe(script)
+  return { layer: Layer.succeed(Messenger, service), recorder }
+}
+
+/** Bare service value + recorder. Use with `Effect.provideService`. */
+export const make = (script: MockMessengerScript = {}) => makeUnsafe(script)