import type { ClarificationRequestMetadata, Message, TaskPendingAction, Turn, } from "@/lib/types/http"; import { isInputCapableSessionState } from "./task-pending-input"; export type PendingClarificationScope = { /** * Undefined means turn history is not loaded, so pendingAction gates the fallback. * Null means history is loaded but has no durable turns, so all messages are hidden. * A string scopes detection to that exact turn. An empty object disables detection. */ currentTurnId?: string | null; pendingAction?: TaskPendingAction | null; }; export function isPendingClarificationMessage(message: Message): boolean { if (message.type !== "clarification_request") return false; const metadata = message.metadata as ClarificationRequestMetadata | undefined; return !metadata?.status || metadata.status === "pending"; } // TurnDTO timestamps are normalized by the backend to UTC with a Z suffix. // Non-Z input falls through to raw comparison and is outside this contract. function durableTurnTimestampKey(value: string): string { const match = /^(.*T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?Z$/.exec(value); if (!match) return value; return `${match[1]}.${(match[2] ?? "").padEnd(9, "0")}Z`; } export function newestDurableTurnId(turns?: readonly Turn[]): string | null | undefined { if (turns === undefined) return undefined; if (turns.length === 0) return null; let newest = turns[0]; for (let index = 1; index < turns.length; index++) { const candidate = turns[index]; const newestKey = [ durableTurnTimestampKey(newest.started_at), durableTurnTimestampKey(newest.created_at), newest.id, ]; const candidateKey = [ durableTurnTimestampKey(candidate.started_at), durableTurnTimestampKey(candidate.created_at), // Mirrors the backend's final deterministic tie-break. Turn IDs do not // encode creation time; exact timestamp ties have no finer ordering. candidate.id, ]; for (let part = 0; part < candidateKey.length; part++) { if (candidateKey[part] === newestKey[part]) continue; if (candidateKey[part] > newestKey[part]) newest = candidate; break; } } return newest.id; } export function clarificationTurnIdForSession( sessionState: string | null | undefined, turns?: readonly Turn[], ): string | null | undefined { if (sessionState && !isInputCapableSessionState(sessionState)) return null; return newestDurableTurnId(turns); } function clarificationMessagesInScope( messages: readonly Message[], scope?: PendingClarificationScope, ): readonly Message[] { if (!scope) return messages; if (scope.pendingAction !== undefined && scope.pendingAction !== "clarification") return []; if (scope.currentTurnId === null) return []; if (scope.currentTurnId === undefined) { return scope.pendingAction === "clarification" ? messages : []; } return messages.filter((message) => message.turn_id === scope.currentTurnId); } function newestMessageTurnId(messages: readonly Message[]): string | undefined { let newest: Message | undefined; for (const message of messages) { if (!message.turn_id) continue; if (!newest) { newest = message; continue; } const createdAt = durableTurnTimestampKey(message.created_at); const newestCreatedAt = durableTurnTimestampKey(newest.created_at); if (createdAt > newestCreatedAt || (createdAt === newestCreatedAt && message.id > newest.id)) { newest = message; } } return newest?.turn_id; } export function findPendingClarification( messages?: readonly Message[] | null, scope?: PendingClarificationScope, ): Message | null { if (!messages?.length) return null; const scoped = clarificationMessagesInScope(messages, scope); // Sidebar callers do not have durable turn history. Use persisted message // order instead of WebSocket arrival order so a delayed predecessor event // cannot hide the current request or re-arm an older one. const latestTurnId = newestMessageTurnId(scoped); for (let i = scoped.length - 1; i >= 0; i--) { if (latestTurnId && scoped[i].turn_id !== latestTurnId) continue; if (scoped[i].type !== "clarification_request") continue; if (isPendingClarificationMessage(scoped[i])) return scoped[i]; } return null; } // findPendingClarificationGroup returns pending clarification_request messages // that share the latest pending message's pending_id, ordered by chat position. // Multi-question bundles emit one message per question; terminal siblings count // toward arrival completeness but are not rendered for a replacement answer. // // Gates on `question_total` from metadata: returns an empty array until the // number of messages received equals the expected bundle size. This prevents // a user from acting on a partially-arrived bundle (clicking an option before // the rest of the N messages have been streamed in via the WS), which would // otherwise trigger a 400 from the backend's all-required gate. export function findPendingClarificationGroup( messages?: readonly Message[] | null, scope?: PendingClarificationScope, ): Message[] { if (!messages) return []; const scoped = clarificationMessagesInScope(messages, scope); const last = findPendingClarification(scoped); if (!last) return []; const meta = last.metadata as ClarificationRequestMetadata | undefined; const pendingID = meta?.pending_id; if (!pendingID) return [last]; const bundle = scoped.filter((m) => { if (m.type !== "clarification_request") return false; const mMeta = m.metadata as ClarificationRequestMetadata | undefined; return mMeta?.pending_id === pendingID; }); const expectedTotal = meta?.question_total; if (typeof expectedTotal === "number" && expectedTotal > 0 && bundle.length < expectedTotal) { return []; } return bundle.filter(isPendingClarificationMessage); } export function hasPendingClarification( messages?: readonly Message[] | null, scope?: PendingClarificationScope, ): boolean { return findPendingClarification(messages, scope) !== null; } export function hasPendingClarificationForSession( messagesBySession: Record, sessionId?: string | null, scope?: PendingClarificationScope, ): boolean { if (!sessionId) return false; return hasPendingClarification(messagesBySession[sessionId], scope); } // --- Permission request helpers --- export function isPendingPermissionMessage(message: Message): boolean { if (message.type !== "permission_request") return false; const metadata = message.metadata as { status?: string } | undefined; return !metadata?.status || metadata.status === "pending"; } // hasPendingPermissionRequest reports whether the *current turn* is blocked // on a permission_request. Scope: // - Scans backwards from the end and stops at the first permission_request // it sees — only the latest one drives the UI. A stale pending row left // behind by an earlier crash followed by a newer approved one must not // light up the amber icon (the agent is no longer blocked on the old row). // - Honours turn boundaries: when the latest message has a turn_id, walking // back to any row that doesn't share it ends the scan (including legacy // rows with null/undefined turn_id). Old turns' permissions can never // leak into the indicator and the scan stays bounded by the current turn // size (typically 5–50 messages) regardless of total session length. // - When the latest message itself has no turn_id (entirely pre-turn-scope // data), boundary enforcement is disabled and we fall back to plain // latest-only semantics across the whole array. export function hasPendingPermissionRequest(messages?: readonly Message[] | null): boolean { if (!messages?.length) return false; const latestTurnId = messages[messages.length - 1].turn_id; for (let i = messages.length - 1; i >= 0; i--) { const m = messages[i]; if (latestTurnId && m.turn_id !== latestTurnId) break; if (m.type !== "permission_request") continue; return isPendingPermissionMessage(m); } return false; } export function hasPendingPermissionForSession( messagesBySession: Record, sessionId?: string | null, ): boolean { if (!sessionId) return false; return hasPendingPermissionRequest(messagesBySession[sessionId]); }