import type { PartMetadata } from 'librechat-data-provider'; /** * The settled state of one tool call, as every part of its card should read * it: the visible label, the `aria-live` announcement, the icon, the shimmer, * and whether a duration is worth showing. * * Before this existed each card derived those independently — the label from * one expression, the announcement from another, the animation from a third — * and a change to one kept missing the others. Thirteen of the seventeen * review findings on #14873 were instances of that drift, and #14892 added a * fourteenth. One value, read everywhere, is what stops it: two presentations * of the same card can no longer disagree about what happened. */ export type ToolCallPhase = 'running' | 'completed' | 'cancelled' | 'failed'; export interface ToolCallPhaseInput { /** * The run's own terminal verdict from `on_run_step_closed`. Absent on parts * saved before the event existed and on endpoints that never emit it, which * is what the heuristic below is for. */ runStepStatus?: PartMetadata['runStepStatus']; /** * The animated value from `useProgress` — what the card is showing right * now. Drives `running` vs `completed` so the label and shimmer follow the * animation rather than snapping. */ displayProgress: number; /** * The progress the stream actually reported, before display animation. * Kept separate because `useProgress` holds below 1 for ~200ms after a call * reports completion (it emits `0.99`, then `1` on a timeout), and the * cancellation inference must not read that lag as an unfinished call. */ reportedProgress: number; /** Whether the whole message is still streaming — a message-level fact. */ isSubmitting: boolean; /** * Whether this call's own result reads as a failure: parsed error output, * or a card-specific signal such as a backgrounded task settling as `error`. */ hasError: boolean; } /** * Resolve a tool call's phase from every signal that bears on it. * * The precedence rules encoded here were each established by a specific * review finding, and each is load-bearing: * * - **An explicit status is authoritative and never gated on output parsing.** * Reading the result text can otherwise demote a step the run reported as * stopped back into an in-flight state. * - **Explicit cancellation outranks a failure-shaped result.** A step the * user stopped is cancelled even if its partial output parses as an error. * - **Under the legacy heuristic the opposite holds: failure outranks * cancellation**, because that inference reads "not submitting and not * finished" as a stop, which a genuine failure also satisfies. Applying the * explicit-close precedence there relabelled real failures as user stops. * - **A closed step is never `running`**, whatever progress says. * - **Cancellation is inferred from reported progress, never from the * animation.** `useProgress` lags a completed call by ~200ms; reading that * lag would label — and announce — a successful call as cancelled whenever * submission ended inside the window. */ export function resolveToolCallPhase({ runStepStatus, displayProgress, reportedProgress, isSubmitting, hasError, }: ToolCallPhaseInput): ToolCallPhase { if (runStepStatus != null) { if (runStepStatus === 'cancelled') { return 'cancelled'; } return runStepStatus === 'failed' || hasError ? 'failed' : 'completed'; } if (hasError) { return 'failed'; } if (!isSubmitting && reportedProgress < 1) { return 'cancelled'; } return displayProgress < 1 ? 'running' : 'completed'; }