Skip to content

🙌 OpenHands: AI-Driven Development

8.6 KB
Raw Blame
import { create } from "zustand";
import { useEventStore } from "#/stores/use-event-store";
import { parseDateAsUTC } from "#/utils/format-time-delta";
import { matchesPendingConversationId } from "#/utils/pending-task-message-link";
import type { BaseEvent } from "#/types/agent-server/core/base/event";

export type PendingUserMessageStatus = "sending" | "error";

/**
 * How long a pending message is allowed to stay in "sending" state before we
 * give up and flip it to "error" with a retry link. This guards against the
 * "server crashed / websocket dropped after our send resolved, echo never
 * arrives" scenario where the message would otherwise hang forever.
 *
 * Exported so tests can override it via vi.fakeTimers without hard-coding the
 * value.
 */
export const PENDING_MESSAGE_TIMEOUT_MS = 150_000;

export interface PendingUserMessage {
  id: string;
  /**
   * The conversation this pending message belongs to. The chat UI filters the
   * global queue by the active conversation id so messages enqueued in one
   * conversation never leak into another when the user switches.
   */
  conversationId: string;
  /** User-visible bubble text (what the user typed; no file annotations). */
  text: string;
  /**
   * The exact string sent to the server (may include the appended
   * "Files uploaded: …" prompt when attachments are present). Used as the
   * primary key when matching against the echoed `UserMessageEvent`.
   */
  content: string;
  status: PendingUserMessageStatus;
  imageUrls: string[];
  fileUrls: string[];
  timestamp: string;
  afterTimestamp?: number;
  errorMessage?: string;
}

interface OptimisticUserMessageState {
  pendingMessages: PendingUserMessage[];
  confirmedEventIds: Set<string>;
}

export interface EnqueuePendingMessagePayload {
  conversationId: string;
  /** User-visible text for the bubble. */
  text: string;
  /**
   * The exact string sent to the server. Defaults to `text` for call sites
   * that don't transform the content (e.g. git-control-bar, task-card).
   */
  content?: string;
  imageUrls?: string[];
  fileUrls?: string[];
  timestamp?: string;
}

interface OptimisticUserMessageActions {
  /**
   * Append a new user message to the queue with status "sending".
   * Returns the locally-generated id for later updates. Schedules a
   * `PENDING_MESSAGE_TIMEOUT_MS` watchdog that flips the entry to "error" if
   * it's still in "sending" state when the timer fires.
   */
  enqueuePendingMessage: (payload: EnqueuePendingMessagePayload) => string;
  /** Mark a pending message as failed (the API rejected it). */
  markPendingMessageError: (id: string, errorMessage?: string) => void;
  /** Mark a pending message as sending again (used when retrying). */
  markPendingMessageSending: (id: string) => void;
  /** Drop a pending message from the queue (e.g., after success/cancellation). */
  removePendingMessage: (id: string) => void;
  /** Match conversation (including task links), server history and content once per event.
   * Prefer a sending attempt; an errored attempt may still receive a late echo. */
  consumeMatchingPendingMessage: (
    conversationId: string,
    content: string,
    event: Pick<BaseEvent, "id" | "timestamp">,
  ) => PendingUserMessage | null;
  /** Wipe all queued messages (e.g., when changing conversations). */
  clearPendingMessages: () => void;
  /**
   * Move pending entries from a provisional task URL (`task-{uuid}`) to the
   * real conversation id once cloud provisioning finishes.
   */
  reassignPendingMessages: (
    fromConversationId: string,
    toConversationId: string,
  ) => void;
}

type OptimisticUserMessageStore = OptimisticUserMessageState &
  OptimisticUserMessageActions;

const initialState: OptimisticUserMessageState = {
  pendingMessages: [],
  confirmedEventIds: new Set(),
};

// Use a timestamp + random suffix instead of a module-level counter so ids
// stay unique across test resets and don't accumulate state between runs.
// `crypto.randomUUID` would be ideal but isn't available in older test
// environments, so a base36 random suffix is a safe lowest-common-denominator.
const generatePendingId = (): string =>
  `pending-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;

const latestServerTimestamp = (conversationId: string): number | undefined => {
  const { events, loadedConversationId } = useEventStore.getState();
  if (
    !loadedConversationId ||
    !matchesPendingConversationId(loadedConversationId, conversationId)
  )
    return undefined;

  let latest: number | undefined;
  for (const event of events) {
    if (!("timestamp" in event) || !event.timestamp) continue;
    const timestamp = parseDateAsUTC(event.timestamp).getTime();
    if (
      Number.isFinite(timestamp) &&
      (latest === undefined || timestamp > latest)
    ) {
      latest = timestamp;
    }
  }
  return latest;
};

export const useOptimisticUserMessageStore = create<OptimisticUserMessageStore>(
  (set, get) => ({
    ...initialState,

    enqueuePendingMessage: (payload) => {
      const id = generatePendingId();
      const message: PendingUserMessage = {
        id,
        conversationId: payload.conversationId,
        text: payload.text,
        content: payload.content ?? payload.text,
        status: "sending",
        imageUrls: payload.imageUrls ?? [],
        fileUrls: payload.fileUrls ?? [],
        timestamp: payload.timestamp ?? new Date().toISOString(),
        afterTimestamp: latestServerTimestamp(payload.conversationId),
      };
      set((state) => ({
        pendingMessages: [...state.pendingMessages, message],
      }));

      // Watchdog: if the server echo never lands (WS dropped, server crashed,
      // network partition), flip this entry to "error" so the user gets a
      // retry link instead of a permanently-pinned "Sending…" bubble.
      setTimeout(() => {
        const current = get().pendingMessages.find((m) => m.id === id);
        if (current?.status === "sending") {
          get().markPendingMessageError(id, "Send timed out");
        }
      }, PENDING_MESSAGE_TIMEOUT_MS);

      return id;
    },

    markPendingMessageError: (id, errorMessage) =>
      set((state) => ({
        pendingMessages: state.pendingMessages.map((message) =>
          message.id === id
            ? { ...message, status: "error", errorMessage }
            : message,
        ),
      })),

    markPendingMessageSending: (id) =>
      set((state) => ({
        pendingMessages: state.pendingMessages.map((message) =>
          message.id === id
            ? {
                ...message,
                status: "sending",
                errorMessage: undefined,
                afterTimestamp: latestServerTimestamp(message.conversationId),
              }
            : message,
        ),
      })),

    removePendingMessage: (id) =>
      set((state) => ({
        pendingMessages: state.pendingMessages.filter(
          (message) => message.id !== id,
        ),
      })),

    consumeMatchingPendingMessage: (conversationId, content, event) => {
      let consumed: PendingUserMessage | null = null;
      const confirmationId = `${conversationId}:${event.id}`;
      const confirmedAt = parseDateAsUTC(event.timestamp).getTime();
      set((state) => {
        if (state.confirmedEventIds.has(confirmationId)) return state;
        // Browser clocks cannot establish ordering against server event history.
        const matches = (message: PendingUserMessage) =>
          matchesPendingConversationId(
            conversationId,
            message.conversationId,
          ) &&
          (message.afterTimestamp === undefined ||
            confirmedAt > message.afterTimestamp) &&
          message.content.trim() === content.trim();
        let target = state.pendingMessages.findIndex(
          (message) => message.status === "sending" && matches(message),
        );
        if (target === -1) target = state.pendingMessages.findIndex(matches);
        if (target === -1) return state;
        consumed = state.pendingMessages[target];
        return {
          pendingMessages: state.pendingMessages.filter(
            (_, index) => index !== target,
          ),
          confirmedEventIds: new Set([
            ...state.confirmedEventIds,
            confirmationId,
          ]),
        };
      });
      return consumed;
    },

    clearPendingMessages: () =>
      set(() => ({ pendingMessages: [], confirmedEventIds: new Set() })),

    reassignPendingMessages: (fromConversationId, toConversationId) =>
      set((state) => ({
        pendingMessages: state.pendingMessages.map((message) =>
          message.conversationId === fromConversationId
            ? { ...message, conversationId: toConversationId }
            : message,
        ),
      })),
  }),
);