sailfork / t3code-github / apps/ web/ src/ components/ chat/ citationProcedure.ts

import { useAtomValue } from "@effect/atom-react";
import { type AtomCommandSuccess, runAtomCommand } from "@t3tools/client-runtime/state/runtime";
import { Atom, type AtomRegistry } from "effect/reactivity";
import type { TimelineEntry } from "../../session-logic";
import { environmentThreadDetails, threadEnvironment } from "../../state/threads";
import { toastManager } from "../ui/toast";
import type { AssistantCitationRequest } from "./AssistantCitationSource";
import type { MessagesTimelineRow } from "./MessagesTimeline.logic";

/** Whether the cited response is in the loaded history, after paging toward it. */
export type CitedHistory =
  | { readonly _tag: "loading" }
  | { readonly _tag: "found" }
  | { readonly _tag: "failed" };

export type CitationPhase =
  | { readonly _tag: "loading" }
  | { readonly _tag: "expanding" }
  | { readonly _tag: "ready"; readonly rowId: string }
  | { readonly _tag: "failed" };

export interface CitedThreadSnapshot {
  readonly message: "assistant" | "other" | null;
  readonly hasMoreHistory: boolean;
  readonly loadFailed?: true;
}

export type CitedHistoryOutcome =
  | { readonly _tag: "found" }
  | { readonly _tag: "failed"; readonly title: string; readonly description: string }
  | { readonly _tag: "aborted" };

type HistoryPageResult = AtomCommandSuccess<
  Awaited<ReturnType<typeof threadEnvironment.loadEarlierHistory.run>>
>;

const MAX_CITATION_PAGES = 20;

const COULD_NOT_LOAD = {
  _tag: "failed",
  title: "Could not load the cited response",
  description:
    "Load earlier turns, then click the citation to try again. Your saved quote is unchanged.",
} as const;

const UNAVAILABLE = {
  _tag: "failed",
  title: "The cited response is unavailable",
  description: "It may have been removed. The selected text is still saved in your citation.",
} as const;

/**
 * Pages history toward the cited message until it is loaded, the thread runs
 * out of history, or loading fails. `readThread` resolves once the thread
 * detail is settled (loaded and no history page in flight), or with null when
 * the signal aborts.
 */
export async function loadCitedHistory(input: {
  readonly signal: AbortSignal;
  readonly readThread: () => Promise<CitedThreadSnapshot | null>;
  readonly loadThrough: () => Promise<HistoryPageResult>;
}): Promise<CitedHistoryOutcome> {
  for (let attempts = 0; ; attempts += 1) {
    const thread = await input.readThread();
    if (thread === null || input.signal.aborted) return { _tag: "aborted" };
    if (thread.loadFailed) return COULD_NOT_LOAD;
    if (thread.message === "assistant") return { _tag: "found" };
    if (thread.message === "other") {
      return {
        _tag: "failed",
        title: "The citation does not refer to an assistant response",
        description: "The selected text is still saved in your citation.",
      };
    }
    if (!thread.hasMoreHistory) return UNAVAILABLE;
    if (attempts >= MAX_CITATION_PAGES) return COULD_NOT_LOAD;
    const result = await input.loadThrough();
    if (input.signal.aborted) return { _tag: "aborted" };
    if (result._tag === "error") return COULD_NOT_LOAD;
    // A noop page means the store has nothing older to load (no cursor, or the
    // thread is gone), so re-reading would only spin on the same snapshot.
    if (result._tag === "noop") return UNAVAILABLE;
  }
}

/** Where the citation stands for the rows the timeline currently shows. */
export function resolveCitationPhase(input: {
  readonly history: CitedHistory;
  readonly messageId: string;
  readonly entries: ReadonlyArray<TimelineEntry>;
  readonly rows: ReadonlyArray<MessagesTimelineRow>;
}): CitationPhase {
  if (input.history._tag === "failed") return { _tag: "failed" };
  const source = input.entries.find(
    (entry) => entry.kind === "message" && entry.message.id === input.messageId,
  );
  // The history store can hold the message a render before the entries do.
  if (!source) return { _tag: "loading" };
  if (source.kind !== "message" || source.message.role !== "assistant") return { _tag: "failed" };
  const row = input.rows.find(
    (candidate) => candidate.kind === "message" && candidate.message.id === input.messageId,
  );
  if (row) return { _tag: "ready", rowId: row.id };
  return { _tag: "expanding" };
}

type ThreadDetail<K extends keyof typeof environmentThreadDetails> = Atom.Type<
  ReturnType<(typeof environmentThreadDetails)[K]>
>;

/**
 * The cited thread as `loadCitedHistory` reads it, or null while it is still
 * settling. A thread that failed to load before any projection arrived counts
 * as settled, so the citation fails instead of waiting on the stream's retries.
 */
export function citedThreadSnapshot(input: {
  readonly thread: ThreadDetail<"quietThreadAtom">;
  readonly history: ThreadDetail<"historyAtom">;
  readonly status: ThreadDetail<"statusAtom">;
  readonly error: ThreadDetail<"errorAtom">;
  readonly messageId: string;
}): CitedThreadSnapshot | null {
  if (input.history.loading) return null;
  if (input.thread === null) {
    if (input.status === "deleted") return { message: null, hasMoreHistory: false };
    return input.error === null ? null : { message: null, hasMoreHistory: false, loadFailed: true };
  }
  // Older pages merge into the visible turn items, not the message list.
  const item = input.thread.projection.visibleTurnItems.find(
    (row) =>
      (row.item.type === "assistant_message" || row.item.type === "user_message") &&
      row.item.messageId === input.messageId,
  )?.item;
  return {
    message: item === undefined ? null : item.type === "assistant_message" ? "assistant" : "other",
    hasMoreHistory: input.history.hasMoreHistory,
  };
}

interface CitedHistoryKey {
  readonly key: string;
  readonly environmentId: AssistantCitationRequest["citation"]["environmentId"];
  readonly threadId: AssistantCitationRequest["citation"]["threadId"];
  readonly messageId: AssistantCitationRequest["citation"]["messageId"];
}

function waitForSettledThread(
  registry: AtomRegistry.AtomRegistry,
  atom: Atom.Atom<CitedThreadSnapshot | null>,
  signal: AbortSignal,
): Promise<CitedThreadSnapshot | null> {
  return new Promise((resolve) => {
    let unsubscribe: (() => void) | null = null;
    let settled = false;
    const finish = (value: CitedThreadSnapshot | null) => {
      if (settled) return;
      settled = true;
      unsubscribe?.();
      signal.removeEventListener("abort", onAbort);
      resolve(value);
    };
    const onAbort = () => finish(null);
    const check = (value: CitedThreadSnapshot | null) => {
      if (value !== null) finish(value);
    };
    signal.addEventListener("abort", onAbort);
    unsubscribe = registry.subscribe(atom, check);
    if (settled) unsubscribe();
    else check(registry.get(atom));
  });
}

/**
 * The citation procedure for one activation (the location key). Mounting it
 * starts paging; leaving the location unmounts it and the finalizer stops it.
 * Plain-object keys compare structurally, so one activation is one procedure.
 */
const citedHistoryAtom = Atom.family(
  ({ key, environmentId, threadId, messageId }: CitedHistoryKey) => {
    const ref = { environmentId, threadId };
    const threadAtom = environmentThreadDetails.quietThreadAtom(ref);
    const historyAtom = environmentThreadDetails.historyAtom(ref);
    const statusAtom = environmentThreadDetails.statusAtom(ref);
    const errorAtom = environmentThreadDetails.errorAtom(ref);
    const settledThreadAtom = Atom.make((get) =>
      citedThreadSnapshot({
        thread: get(threadAtom),
        history: get(historyAtom),
        status: get(statusAtom),
        error: get(errorAtom),
        messageId,
      }),
    );
    return Atom.make((get): CitedHistory => {
      const controller = new AbortController();
      get.addFinalizer(() => controller.abort());
      void loadCitedHistory({
        signal: controller.signal,
        readThread: () => waitForSettledThread(get.registry, settledThreadAtom, controller.signal),
        loadThrough: async () => {
          const result = await runAtomCommand(
            get.registry,
            threadEnvironment.loadEarlierHistory,
            { environmentId, input: { threadId, throughEntryId: messageId } },
            { label: "load cited thread history", reportFailure: false },
          );
          return result._tag === "Success"
            ? result.value
            : { _tag: "error", message: "Could not load history." };
        },
      }).then((outcome) => {
        if (outcome._tag === "aborted") return;
        if (outcome._tag === "failed") {
          toastManager.add({
            type: "warning",
            title: outcome.title,
            description: outcome.description,
          });
        }
        get.setSelf({ _tag: outcome._tag });
      });
      return { _tag: "loading" };
    }).pipe(Atom.withLabel(`assistant-citation:history:${key}`));
  },
);

const NO_CITED_HISTORY_ATOM = Atom.make<CitedHistory>({ _tag: "loading" });

export function useCitedHistory(request: AssistantCitationRequest | null): CitedHistory {
  return useAtomValue(
    request === null
      ? NO_CITED_HISTORY_ATOM
      : citedHistoryAtom({
          key: request.key,
          environmentId: request.citation.environmentId,
          threadId: request.citation.threadId,
          messageId: request.citation.messageId,
        }),
  );
}