Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

16.8 KB
Raw Blame
import type * as RpcGroup from "effect/unstable/rpc/RpcGroup";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Stream from "effect/Stream";
import {
  type OrchestrationEvent,
  OrchestrationGetSnapshotError,
  ORCHESTRATION_WS_METHODS,
  WsRpcGroup,
} from "@akeru/contracts";
import {
  projectActivityEvent,
  projectThreadDetailSnapshot,
} from "./orchestration/ActivityPayloadProjection.ts";
import { threadLiveEventCoalescer } from "./orchestration/ThreadLiveEventCoalescer.ts";
import { liveStreamBudget, type RetainedLiveItem } from "./orchestration/LiveStreamBudget.ts";

import {
  isThreadDetailEvent,
  toShellSourceEvent,
  createSentThreadShells,
  SHELL_RESUME_MAX_GAP,
  THREAD_RESUME_MAX_EVENTS,
  ORCHESTRATION_REPLAY_PAYLOAD_BUDGET_BYTES,
} from "./wsSupport.ts";
import type { WsConnection } from "./wsConnection.ts";
import type { ShellLiveInput } from "./wsOrchestrationStreams.ts";

export const createWsOrchestrationSubscriptions = ({
  projectionSnapshotQuery,
  orchestrationEngine,
  canReplayPersistedRange,
  channelBindingsForRuntime,
  observeRpcStreamEffect,
  loadEnvironmentPeople,
  SHELL_COALESCE_WINDOW,
  SHELL_COALESCE_MAX_CHUNK,
  coalesceShellStream,
  coalesceShellLiveInputs,
}: Pick<
  WsConnection,
  | "projectionSnapshotQuery"
  | "orchestrationEngine"
  | "canReplayPersistedRange"
  | "channelBindingsForRuntime"
  | "observeRpcStreamEffect"
  | "loadEnvironmentPeople"
  | "SHELL_COALESCE_WINDOW"
  | "SHELL_COALESCE_MAX_CHUNK"
  | "coalesceShellStream"
  | "coalesceShellLiveInputs"
>) =>
  ({
    [ORCHESTRATION_WS_METHODS.subscribeShell]: (input) =>
      observeRpcStreamEffect(
        ORCHESTRATION_WS_METHODS.subscribeShell,
        Effect.gen(function* () {
          // Coalesce the live shell stream per aggregate over a small window
          // so bursts of high-frequency events (streaming message deltas,
          // activity appends) collapse into a single shell refetch and never
          // serialize a brand-new thread's `thread.created` behind hundreds
          // of per-event DB reads. See coalesceShellStream.
          // Attach live delivery into a scope-bound buffer BEFORE loading any
          // snapshot or draining catch-up, otherwise an event published while
          // the snapshot query is in flight is lost (it is past the snapshot's
          // sequence but the live subscription is not attached yet). Every
          // path below emits from this same buffered live tail. Overlapping
          // events are deduped by sequence on the client.
          const liveBudget = yield* liveStreamBudget();
          const sentThreads = createSentThreadShells();

          const liveBuffer = yield* Queue.unbounded<
            RetainedLiveItem<ShellLiveInput>,
            OrchestrationGetSnapshotError
          >();

          let liveBufferClosed = false;

          const closeLiveBuffer = (error?: OrchestrationGetSnapshotError) =>
            Effect.gen(function* () {
              if (liveBufferClosed) {
                return;
              }

              liveBufferClosed = true;
              liveBudget.release(yield* Queue.clear(liveBuffer).pipe(Effect.orDie));

              if (error) {
                yield* Queue.fail(liveBuffer, error);
              }

              yield* Queue.shutdown(liveBuffer);
            });

          yield* Effect.addFinalizer(() => closeLiveBuffer());
          yield* liveBudget.failed.pipe(
            Effect.catchTags({ OrchestrationGetSnapshotError: closeLiveBuffer }),
            Effect.forkScoped,
          );
          yield* Effect.forkScoped(
            orchestrationEngine.streamDomainEvents.pipe(
              Stream.runForEach((event) =>
                // Retain only what the shell reads. A thread refetch needs
                // the thread id and sequence, not a large message or tool
                // payload, so the budget charges the small reference.
                liveBudget
                  .retain({ kind: "event" as const, event: toShellSourceEvent(event) })
                  .pipe(
                    Effect.flatMap((item) => Queue.offer(liveBuffer, item)),
                    Effect.uninterruptible,
                  ),
              ),
              // Stop the PubSub consumer even if RPC delivery is waiting
              // for an ACK and never pulls the failed buffer again.
              Effect.raceFirst(liveBudget.failed),
              Effect.catchTags({ OrchestrationGetSnapshotError: () => Effect.void }),
            ),
            { startImmediately: true },
          );

          const coalesceRetainedInputs = (items: ReadonlyArray<RetainedLiveItem<ShellLiveInput>>) =>
            coalesceShellLiveInputs(
              items.map((item) => item.value),
              sentThreads,
            ).pipe(Effect.flatMap((output) => liveBudget.replace(items, output)));

          const bufferedLiveStream = Stream.fromQueue(liveBuffer).pipe(
            Stream.groupedWithin(SHELL_COALESCE_MAX_CHUNK, SHELL_COALESCE_WINDOW),
            Stream.mapEffect(coalesceRetainedInputs),
            Stream.flatMap((items) => Stream.fromIterable(items)),
          );

          const loadSnapshot = Effect.all({
            snapshot: projectionSnapshotQuery.getShellSnapshot(),
            people: loadEnvironmentPeople(),
          }).pipe(
            Effect.map(({ snapshot, people }) => ({
              ...snapshot,
              currentPersonId: people.current.personId,
              currentPersonDisplayName: people.current.displayName,
              ...(people.host === undefined
                ? {}
                : {
                    environmentHostPersonId: people.host.personId,
                    environmentHostDisplayName: people.host.displayName,
                  }),
              bots: snapshot.bots.map((bot) => ({
                ...bot,
                channelBindings: channelBindingsForRuntime(bot.channelBindings ?? []),
              })),
            })),
            Effect.tapError((cause) =>
              Effect.logError("orchestration shell snapshot load failed", { cause }),
            ),
            Effect.mapError(
              (cause) =>
                new OrchestrationGetSnapshotError({
                  message: "Failed to load orchestration shell snapshot",
                  cause,
                }),
            ),
          );

          // Offer the completion marker into the same queue as live events.
          // Anything buffered while snapshot/replay work was in flight is
          // therefore delivered before the client is told it is synchronized.
          const synchronizedThenLive = liveBudget.deliver(
            input.requestCompletionMarker === true
              ? Stream.concat(
                  Stream.fromEffect(
                    liveBudget.retain({ kind: "synchronized" as const }).pipe(
                      Effect.flatMap((item) => Queue.offer(liveBuffer, item)),
                      Effect.uninterruptible,
                      Effect.andThen(Queue.takeAll(liveBuffer)),
                      Effect.flatMap(coalesceRetainedInputs),
                    ),
                  ).pipe(Stream.flatMap((items) => Stream.fromIterable(items))),
                  bufferedLiveStream,
                )
              : bufferedLiveStream,
          );

          // When the client already holds a shell snapshot (cached, or loaded
          // over HTTP) it passes that snapshot's sequence, and we resume by
          // replaying shell events after it instead of re-sending the whole
          // projects/threads list over the socket. If the client is too far
          // behind, we fall back to a fresh snapshot instead of an unbounded
          // replay (see below).
          if (input.afterSequence !== undefined) {
            const afterSequence = input.afterSequence;
            const headSequence = yield* orchestrationEngine.latestSequence;
            const replayGap = headSequence - afterSequence;

            // Gap too large: replaying every intervening event (each a shell
            // refetch) is far more expensive than a single O(active-threads)
            // snapshot. A cursor ahead of this engine's authoritative state
            // is also invalid, so reset it with a snapshot. Send the snapshot
            // followed by the buffered live tail, exactly as the
            // no-afterSequence path does.
            if (
              !(yield* canReplayPersistedRange(afterSequence, headSequence, SHELL_RESUME_MAX_GAP))
            ) {
              const snapshot = yield* loadSnapshot;

              return Stream.concat(
                Stream.make({ kind: "snapshot" as const, snapshot }),
                synchronizedThenLive,
              );
            }

            const catchUpStream = coalesceShellStream(
              // Replay only through the head captured above. Newer events
              // are already covered by the live subscription, so this bound
              // cannot chase a moving event-store head or grow the live
              // buffer indefinitely while waiting for an empty page.
              orchestrationEngine.readEvents(afterSequence, replayGap, headSequence),
              sentThreads,
            ).pipe(
              Stream.mapError(
                (cause) =>
                  new OrchestrationGetSnapshotError({
                    message: "Failed to replay orchestration shell events",
                    cause,
                  }),
              ),
            );

            return Stream.concat(catchUpStream, synchronizedThenLive);
          }

          const snapshot = yield* loadSnapshot;

          return Stream.concat(
            Stream.make({
              kind: "snapshot" as const,
              snapshot,
            }),
            synchronizedThenLive,
          );
        }),
        { "rpc.aggregate": "orchestration" },
      ),

    [ORCHESTRATION_WS_METHODS.subscribeThread]: (input) =>
      observeRpcStreamEffect(
        ORCHESTRATION_WS_METHODS.subscribeThread,
        Effect.gen(function* () {
          const isThisThreadDetailEvent = (event: OrchestrationEvent) =>
            event.aggregateKind === "thread" &&
            event.aggregateId === input.threadId &&
            isThreadDetailEvent(event);

          const liveStream = orchestrationEngine.streamDomainEvents.pipe(
            Stream.filter(isThisThreadDetailEvent),
            Stream.map((event) => ({
              kind: "event" as const,
              event,
            })),
          );

          // Attach live delivery before reading either replay or snapshot state.
          // Otherwise an event published while the snapshot is loading is lost.
          const liveBuffer = yield* threadLiveEventCoalescer();
          yield* Effect.forkScoped(
            liveStream.pipe(
              Stream.runForEachArray(liveBuffer.offerAll),
              Effect.raceFirst(liveBuffer.failed),
              Effect.catchTags({ OrchestrationGetSnapshotError: () => Effect.void }),
            ),
            { startImmediately: true },
          );
          const bufferedLiveStream = liveBuffer.stream;
          let replayOnMissingSnapshot: typeof bufferedLiveStream | undefined;

          // When the client already loaded the snapshot over HTTP it passes
          // that snapshot's sequence, and we resume the live subscription by
          // replaying persisted events after it instead of re-sending the
          // (potentially multi-KB) snapshot frame over the socket.
          //
          // The live PubSub subscription must be attached *before* draining
          // the catch-up replay, otherwise events published during the replay
          // window are dropped (they are past the persisted tail the replay
          // read, but the live stream is not yet subscribed). So fork the
          // live stream into a buffer bound to this stream's scope, then emit
          // catch-up followed by the buffered/ongoing live events. Overlapping
          // events are deduped by sequence on the client.
          //
          // Measure only this thread's rows. Global sequence gaps can
          // contain unrelated or pruned streams. Keep an explicit upper
          // bound so events after the captured head stay in the live tail.
          if (input.afterSequence !== undefined) {
            const afterSequence = input.afterSequence;
            const headSequence = yield* orchestrationEngine.latestSequence;

            const range = {
              threadId: input.threadId,
              fromSequenceExclusive: afterSequence,
              toSequenceInclusive: headSequence,
            };

            const replayStats =
              afterSequence > headSequence
                ? null
                : yield* orchestrationEngine
                    .getThreadReplayStats({
                      ...range,
                      maxEvents: THREAD_RESUME_MAX_EVENTS,
                    })
                    .pipe(
                      Effect.mapError(
                        (cause) =>
                          new OrchestrationGetSnapshotError({
                            message: `Failed to measure chat ${input.threadId} replay range`,
                            cause,
                          }),
                      ),
                    );

            if (
              replayStats !== null &&
              replayStats.eventCount <= THREAD_RESUME_MAX_EVENTS &&
              replayStats.payloadBytes <= ORCHESTRATION_REPLAY_PAYLOAD_BUDGET_BYTES
            ) {
              const catchUpStream = orchestrationEngine
                .readThreadEvents({ ...range, limit: THREAD_RESUME_MAX_EVENTS })
                .pipe(
                  Stream.filter(isThisThreadDetailEvent),
                  Stream.map((event) => ({
                    kind: "event" as const,
                    event: projectActivityEvent(event),
                  })),
                  Stream.mapError(
                    (cause) =>
                      new OrchestrationGetSnapshotError({
                        message: `Failed to restore chat ${input.threadId}`,
                        cause,
                      }),
                  ),
                );

              const afterCatchUp =
                input.requestCompletionMarker === true
                  ? Stream.unwrap(
                      liveBuffer
                        .offer({ kind: "synchronized" as const })
                        .pipe(Effect.as(bufferedLiveStream)),
                    )
                  : bufferedLiveStream;

              const replay = Stream.concat(catchUpStream, afterCatchUp);

              if (!replayStats.hasCreateEvent) {
                return replay;
              }

              replayOnMissingSnapshot = replay;
            }
            // A recreated thread needs a fresh snapshot if it still exists.
            // Oversized replays and invalid cursors also use the snapshot path.
          }

          const snapshot = yield* projectionSnapshotQuery
            .getThreadDetailSnapshot(
              input.threadId,
              // Windowing the fallback snapshot is opt-in per subscription:
              // clients that don't send turnLimit (including all
              // pre-pagination clients) get the full thread, since they
              // have no way to load older pages.
              input.turnLimit === undefined ? undefined : { turnLimit: input.turnLimit },
            )
            .pipe(
              Effect.mapError(
                (cause) =>
                  new OrchestrationGetSnapshotError({
                    message: `Failed to load chat ${input.threadId}`,
                    cause,
                  }),
              ),
            );

          if (Option.isNone(snapshot)) {
            // The recreated thread can already be deleted. Preserve the
            // bounded replay and shell removal instead of retrying a
            // snapshot that cannot exist. Oversized ranges still fail.
            if (replayOnMissingSnapshot !== undefined) {
              return replayOnMissingSnapshot;
            }

            return yield* new OrchestrationGetSnapshotError({
              message: `Chat ${input.threadId} was not found`,
              cause: input.threadId,
            });
          }

          const afterSnapshot =
            input.requestCompletionMarker === true
              ? Stream.unwrap(
                  liveBuffer
                    .offer({ kind: "synchronized" as const })
                    .pipe(Effect.as(bufferedLiveStream)),
                )
              : bufferedLiveStream;

          return Stream.concat(
            Stream.make({
              kind: "snapshot" as const,
              snapshot: projectThreadDetailSnapshot(snapshot.value),
            }),
            afterSnapshot,
          );
        }),
        { "rpc.aggregate": "orchestration" },
      ),
  }) satisfies Pick<
    RpcGroup.HandlersFrom<RpcGroup.Rpcs<typeof WsRpcGroup>>,
    typeof ORCHESTRATION_WS_METHODS.subscribeShell | typeof ORCHESTRATION_WS_METHODS.subscribeThread
  >;