Skip to content

πŸ™Œ OpenHands: AI-Driven Development

11.3 KB
Raw Blame
import { OpenHandsEvent } from "#/types/agent-server/core";
import {
  isACPToolCallEvent,
  isActionEvent,
  isObservationEvent,
  isStreamingDeltaEvent,
  isUserRejectObservation,
} from "#/types/agent-server/type-guards";
import { StreamingDeltaEvent } from "#/types/agent-server/core/events/streaming-delta-event";
import type {
  DeltaFrame,
  ItemStartedFrame,
} from "#/types/agent-server/session-frames";

/**
 * An event as held by the UI list. `seq` is the log index a `durable` frame
 * carried; slots and transient events have none, which is what makes "has a
 * seq" mean "is resumable".
 */
export type UIEvent = OpenHandsEvent & {
  isFromPlanningAgent?: boolean;
  seq?: number;
};

export interface StreamingSlotMeta {
  isFromPlanningAgent?: boolean;
}

const attemptOf = (slot: StreamingDeltaEvent): number => slot.attempt ?? 1;

/** Slots and events belong to one socket; `seq` only means anything within it. */
const isSameSocket = (event: UIEvent, isFromPlanningAgent: boolean): boolean =>
  Boolean(event.isFromPlanningAgent) === isFromPlanningAgent;

// `item_id` is a uuid, so the slot lookup needs no socket scoping.
const findSlotIndex = (uiEvents: UIEvent[], itemId: string): number =>
  uiEvents.findIndex(
    (event) => isStreamingDeltaEvent(event) && event.id === itemId,
  );

/**
 * Where a slot anchored after `anchorSeq` belongs: before the first event the
 * server sequenced after it. This is what keeps a user message that lands
 * mid-stream *below* the bubble instead of splitting it (#15433).
 *
 * `seq` is an index into *one* conversation's log, and the main and planning
 * sockets are different conversations whose logs both start at 0, so the scan
 * must stay inside the slot's own socket or it lands in the other's history.
 */
const slotInsertIndex = (
  uiEvents: UIEvent[],
  anchorSeq: number | null | undefined,
  isFromPlanningAgent: boolean,
): number => {
  if (anchorSeq === null || anchorSeq === undefined) {
    return uiEvents.length;
  }
  const index = uiEvents.findIndex(
    (event) =>
      event.seq !== undefined &&
      isSameSocket(event, isFromPlanningAgent) &&
      event.seq > anchorSeq,
  );
  return index === -1 ? uiEvents.length : index;
};

/** The anchor event itself, or the nearest earlier event from the same socket. */
const findAnchor = (
  uiEvents: UIEvent[],
  anchorSeq: number | null | undefined,
  isFromPlanningAgent: boolean,
  insertIndex: number,
): UIEvent | undefined => {
  if (anchorSeq !== null && anchorSeq !== undefined) {
    const exact = uiEvents.find(
      (event) =>
        event.seq === anchorSeq && isSameSocket(event, isFromPlanningAgent),
    );
    if (exact) {
      return exact;
    }
  }
  // No `findLast` under lib es2022.
  for (let i = insertIndex - 1; i >= 0; i -= 1) {
    if (isSameSocket(uiEvents[i], isFromPlanningAgent)) {
      return uiEvents[i];
    }
  }
  return undefined;
};

/**
 * Open (or re-open, for a higher attempt) the slot an `item_started` frame
 * announces. A lower or equal attempt is ignored.
 */
export const openStreamingSlot = (
  frame: ItemStartedFrame,
  uiEvents: UIEvent[],
  meta: StreamingSlotMeta = {},
): UIEvent[] => {
  const attempt = frame.attempt ?? 1;
  const existingIndex = findSlotIndex(uiEvents, frame.item_id);

  if (existingIndex !== -1) {
    const slot = uiEvents[existingIndex] as StreamingDeltaEvent;
    // Only a higher attempt supersedes; a repeat of the current one is a no-op.
    if (attemptOf(slot) >= attempt) {
      return uiEvents;
    }
    const next = [...uiEvents];
    next[existingIndex] = {
      ...slot,
      attempt,
      content: null,
      reasoning_content: null,
    };
    return next;
  }

  const isFromPlanningAgent = Boolean(meta.isFromPlanningAgent);
  const insertIndex = slotInsertIndex(
    uiEvents,
    frame.anchor_seq,
    isFromPlanningAgent,
  );
  // Borrow the anchor's timestamp so the store's timestamp sort β€” which fires
  // whenever durable frames arrive out of order, as they routinely do β€” keeps
  // the slot right after it. Prefer the anchor event itself: a neighbour may be
  // a client-stamped event whose clock does not match the server's.
  const anchor = findAnchor(
    uiEvents,
    frame.anchor_seq,
    isFromPlanningAgent,
    insertIndex,
  );
  const slot: StreamingDeltaEvent & StreamingSlotMeta = {
    kind: "StreamingDeltaEvent",
    id: frame.item_id,
    source: "agent",
    timestamp:
      anchor && "timestamp" in anchor && anchor.timestamp
        ? anchor.timestamp
        : new Date().toISOString(),
    content: null,
    reasoning_content: null,
    attempt,
    ...meta,
  };

  const next = [...uiEvents];
  next.splice(insertIndex, 0, slot);
  return next;
};

/**
 * Append a batch of `delta` frames to their slots.
 *
 * A delta with no open slot opens one: its `item_started` went by before this
 * socket connected (progress frames are never replayed) β€” which is the normal
 * case for the first reply of a conversation started from the home page, since
 * the socket waits for the history load. This cannot orphan a bubble: slots
 * and buffered deltas are discarded on connect and disconnect, so the delta is
 * live on this connection, and the server retires every stream on it. The one
 * race β€” a delta overtaken by its own durable event, which travels a different
 * fan-out β€” is closed by `isFinished`.
 */
export const appendStreamingDeltas = (
  frames: DeltaFrame[],
  uiEvents: UIEvent[],
  {
    isFinished = () => false,
    ...meta
  }: StreamingSlotMeta & { isFinished?: (itemId: string) => boolean } = {},
): UIEvent[] => {
  let next = uiEvents;
  let copied = false;

  for (const frame of frames) {
    let index = findSlotIndex(next, frame.item_id);
    if (index === -1) {
      if (isFinished(frame.item_id)) {
        continue;
      }
      next = openStreamingSlot(
        {
          type: "item_started",
          item_id: frame.item_id,
          attempt: frame.attempt,
        },
        next,
        meta,
      );
      copied = true;
      index = findSlotIndex(next, frame.item_id);
    }
    const slot = next[index] as StreamingDeltaEvent;
    const attempt = frame.attempt ?? 1;
    if (attempt < attemptOf(slot)) {
      continue;
    }
    // A higher attempt re-streams the item, so the old tail is superseded.
    const superseded = attempt > attemptOf(slot);
    const content = superseded ? "" : (slot.content ?? "");
    const reasoning = superseded ? "" : (slot.reasoning_content ?? "");
    const isReasoning = frame.kind === "reasoning";

    if (!copied) {
      next = [...next];
      copied = true;
    }
    next[index] = {
      ...slot,
      attempt,
      content: (isReasoning ? content : content + frame.content) || null,
      reasoning_content:
        (isReasoning ? reasoning + frame.content : reasoning) || null,
    };
  }

  return next;
};

/**
 * Drop the slot for `itemId`. Used by `item_aborted`: the stream ended without
 * a durable event, so nothing is coming to supersede the provisional text.
 */
export const abortStreamingSlot = (
  itemId: string,
  uiEvents: UIEvent[],
  attempt?: number,
): UIEvent[] => {
  const index = findSlotIndex(uiEvents, itemId);
  if (index === -1) {
    return uiEvents;
  }
  // An abort for a superseded attempt must not delete the live retry's slot.
  if (
    attempt !== undefined &&
    attempt < attemptOf(uiEvents[index] as StreamingDeltaEvent)
  ) {
    return uiEvents;
  }
  return uiEvents.filter((_, position) => position !== index);
};

/**
 * Drop every open slot for one socket. Called on connect and disconnect:
 * progress frames are never replayed, so an open slot cannot survive the gap,
 * and the message it was standing in for arrives on the durable cursor.
 */
export const clearStreamingSlots = (
  uiEvents: UIEvent[],
  isFromPlanningAgent = false,
): UIEvent[] => {
  const next = uiEvents.filter(
    (event) =>
      !isStreamingDeltaEvent(event) ||
      !isSameSocket(event as UIEvent, isFromPlanningAgent),
  );
  return next.length === uiEvents.length ? uiEvents : next;
};

/**
 * Handles adding an event to the UI events array
 * Replaces actions with observations when they arrive (so UI shows observation instead of action)
 * Exception: ThinkAction is NOT replaced because the thought content is in the action, not in the observation
 *
 * ACPToolCallEvent merge: the SDK emits two events per ``tool_call_id`` β€” an
 * early ``started`` event (``pending`` / ``in_progress``) and one terminal
 * (completed / failed) event, the action->observation pair for a tool call.
 * Replace the started entry in place with the terminal one so a single card
 * updates from running to its result, exactly like an observation superseding
 * its action below.
 */
export const handleEventForUI = (
  event: UIEvent,
  uiEvents: UIEvent[],
): UIEvent[] => {
  const newUiEvents = [...uiEvents];

  // The durable event *is* the item: the SDK mints its id when the stream
  // opens, so one equality test retires the slot β€” and replacing in place
  // keeps the finished message where the streamed text already was.
  const eventId = "id" in event ? event.id : undefined;
  if (eventId !== undefined) {
    const slotIndex = findSlotIndex(newUiEvents, eventId);
    if (slotIndex !== -1) {
      newUiEvents[slotIndex] = event;
      return newUiEvents;
    }
  }

  if (isACPToolCallEvent(event)) {
    const existingIndex = newUiEvents.findIndex(
      (uiEvent) =>
        isACPToolCallEvent(uiEvent) &&
        uiEvent.tool_call_id === event.tool_call_id,
    );
    if (existingIndex !== -1) {
      newUiEvents[existingIndex] = event;
    } else {
      newUiEvents.push(event);
    }
    return newUiEvents;
  }

  if (isObservationEvent(event)) {
    // Don't add ThinkObservation at all - we keep the ThinkAction instead
    // The thought content is in the action, not the observation
    if (event.observation.kind === "ThinkObservation") {
      return newUiEvents;
    }

    // Don't add FinishObservation at all - we keep the FinishAction instead
    // Both contain the same message content, so we only need to display one
    // This also prevents duplicate messages when events arrive out of order due to React batching
    if (event.observation.kind === "FinishObservation") {
      return newUiEvents;
    }
  }

  if (isUserRejectObservation(event)) {
    // Like their observations above, a rejection never replaces a ThinkAction
    // or FinishAction: the content to display is in the action itself
    const rejectedAction = newUiEvents.find(
      (uiEvent) => uiEvent.id === event.action_id,
    );
    if (
      rejectedAction &&
      isActionEvent(rejectedAction) &&
      (rejectedAction.action.kind === "ThinkAction" ||
        rejectedAction.action.kind === "FinishAction")
    ) {
      return newUiEvents;
    }
  }

  // A UserRejectObservation resolves its action just like an observation
  // does; left unreplaced, the rejected action would keep reading as in flight.
  if (isObservationEvent(event) || isUserRejectObservation(event)) {
    // Find and replace the corresponding action from uiEvents
    const actionIndex = newUiEvents.findIndex(
      (uiEvent) => uiEvent.id === event.action_id,
    );
    if (actionIndex !== -1) {
      newUiEvents[actionIndex] = event;
    } else {
      // Action not found in uiEvents, just add the observation
      newUiEvents.push(event);
    }
  } else {
    // For non-observation events, just add them to uiEvents
    newUiEvents.push(event);
  }

  return newUiEvents;
};