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

import type { OrchestrationV2Run, OrchestrationV2RunStatus, RunId } from "@t3tools/contracts";
import { latestExecutedRun } from "@t3tools/shared/orchestrationV2ThreadError";

export type ThreadActivityStatus = "working" | "approval" | "input" | "idle";

/** Background threads say these too, so a status sounds the same wherever it's heard. */
export const THREAD_STATUS_TEXT = {
  approval: "Needs approval",
  input: "Needs your input",
  done: "Done",
  failed: "Failed",
  stopped: "Stopped",
} as const;

export interface ThreadActivitySnapshot {
  readonly status: ThreadActivityStatus;
  /** The pending approval or question, when there is one. */
  readonly requestId: string | null;
  readonly runId: RunId | null;
  readonly runStatus: OrchestrationV2RunStatus | null;
}

export interface ThreadAnnouncementMemory {
  readonly snapshot: ThreadActivitySnapshot;
  /**
   * The turn under way: the run it belongs to, "unknown" until that run shows
   * up, or null between turns. Its ending is announced once, then it clears.
   */
  readonly turnRunId: RunId | "unknown" | null;
  /** The run whose ending is already known, so a stale run is never announced as this turn's. */
  readonly settledRunId: RunId | null;
  /** The run shown while idle belongs to the last turn, even if it is still settling. */
  readonly idleRunId: RunId | null;
}

const ACTIVE_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
  "preparing",
  "starting",
  "running",
  "waiting",
]);

const STARTING_RUN_STATUSES: ReadonlySet<OrchestrationV2RunStatus | null> = new Set([
  "queued",
  "preparing",
  "starting",
]);

export function runOutcomeText(status: OrchestrationV2RunStatus | null): string | null {
  switch (status) {
    case "completed":
      return THREAD_STATUS_TEXT.done;
    case "failed":
      return THREAD_STATUS_TEXT.failed;
    case "interrupted":
    case "cancelled":
      return THREAD_STATUS_TEXT.stopped;
    default:
      return null;
  }
}

interface RunState {
  readonly runId: RunId;
  readonly status: OrchestrationV2RunStatus;
}

/**
 * The thread's detail hasn't caught up with the live thread shell: it isn't
 * loaded yet, or a cached copy still shows an older run or state. Reading such
 * a frame as the baseline replays what already happened, so it's skipped.
 */
export function isDetailBehindShell(detailRun: RunState | null, shellRun: RunState | null) {
  return (
    shellRun !== null &&
    (detailRun?.runId !== shellRun.runId || detailRun.status !== shellRun.status)
  );
}

/**
 * A queued message cancelled before it started keeps its place in line, so it
 * shows up as the thread's latest run. It never ran, so the turn ended however
 * the last run that did ran.
 */
export function announcedRun(
  activityRun: (RunState & { readonly startedAt: string | null }) | null,
  runs: ReadonlyArray<OrchestrationV2Run>,
): RunState | null {
  if (activityRun?.status !== "cancelled" || activityRun.startedAt !== null) return activityRun;
  const run = latestExecutedRun(runs);
  return run === null ? null : { runId: run.id, status: run.status };
}

/**
 * Decides what a screen reader hears when the open thread's turn changes state.
 * The first snapshot of a thread is a silent baseline, so opening or switching
 * threads never replays what already happened.
 */
export function nextThreadAnnouncement(
  previous: ThreadAnnouncementMemory | null,
  next: ThreadActivitySnapshot,
): { readonly memory: ThreadAnnouncementMemory; readonly announcement: string | null } {
  const idle = next.status === "idle";
  // A run still starting up while the thread looks idle (a queued message,
  // a resume) is the next turn's, not a leftover from the last one.
  const idleRunId =
    idle && !STARTING_RUN_STATUSES.has(next.runStatus) ? next.runId : (previous?.idleRunId ?? null);
  // A run doing new work; the run left over from the last turn doesn't count.
  const newRunId =
    !idle && ACTIVE_RUN_STATUSES.has(next.runStatus) && next.runId !== idleRunId
      ? next.runId
      : null;

  if (previous === null) {
    return {
      memory: {
        snapshot: next,
        turnRunId: idle ? null : (newRunId ?? "unknown"),
        settledRunId: runOutcomeText(next.runStatus) === null ? null : next.runId,
        idleRunId,
      },
      announcement: null,
    };
  }
  const memory = { ...previous, snapshot: next, idleRunId };
  const { turnRunId } = previous;

  if (!idle) {
    // Sending can look idle for a moment before the server reports the run,
    // so a turn is tied to its run as soon as one appears, and only another
    // run taking over (a queued message starting) is a new turn.
    const turnStarted =
      turnRunId === null ||
      (newRunId !== null && turnRunId !== "unknown" && newRunId !== turnRunId);
    const nextTurnRunId =
      turnStarted || turnRunId === "unknown" ? (newRunId ?? "unknown") : turnRunId;
    const announcement =
      next.status === "approval"
        ? previous.snapshot.status === "approval" && previous.snapshot.requestId === next.requestId
          ? null
          : THREAD_STATUS_TEXT.approval
        : next.status === "input"
          ? previous.snapshot.status === "input" && previous.snapshot.requestId === next.requestId
            ? null
            : THREAD_STATUS_TEXT.input
          : turnStarted
            ? "Working"
            : null;
    return { memory: { ...memory, turnRunId: nextTurnRunId }, announcement };
  }

  // Work can stop a moment before the run settles; the ending waits for the run.
  const outcome = runOutcomeText(next.runStatus);
  if (turnRunId === null) {
    // A run that settled unseen is history too, or the next failed send would claim it.
    const settledRunId = outcome === null ? previous.settledRunId : next.runId;
    return { memory: { ...memory, settledRunId }, announcement: null };
  }
  if (next.runStatus === "rolled_back") {
    return { memory: { ...memory, turnRunId: null, settledRunId: next.runId }, announcement: null };
  }
  if (outcome === null) return { memory, announcement: null };
  // Work stopped without a new run, e.g. a send that failed; the retry is a new turn.
  if (next.runId === previous.settledRunId) {
    return { memory: { ...memory, turnRunId: null }, announcement: null };
  }
  // The last turn's run settling while this turn waits for its own run is not this turn's ending.
  if (turnRunId === "unknown" && next.runId === previous.idleRunId) {
    return { memory: { ...memory, settledRunId: next.runId }, announcement: null };
  }
  return {
    memory: { ...memory, turnRunId: null, settledRunId: next.runId },
    announcement: outcome,
  };
}