feat: integrate HITL phase management across tool components

- Refactored ApprovalCard in various tools (Gmail, Google Calendar, Google Drive) to utilize the new useHitlPhase hook for improved state management. - Updated logic to handle tool action phases (pending, processing, complete, rejected) consistently across components, enhancing user feedback during interactions. - Simplified decision handling by removing direct state management for approval decisions, streamlining the approval process. - Enhanced UI feedback to reflect the current phase of tool actions, improving user experience during tool interactions.
2026-04-26 01:06:23 +02:00 · 2026-03-21 11:18:35 +05:30 · 2026-03-21 11:18:35 +05:30 · 9cd2c1f712
commit 9cd2c1f712
parent ff6514a99f
19 changed files with 706 additions and 590 deletions
--- a/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/create-linear-issue.tsx
@ -15,6 +15,7 @@ import {
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
+import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { useSetAtom } from "jotai";
 import { openHitlEditPanelAtom } from "@/atoms/chat/hitl-edit-panel.atom";

@ -66,6 +67,7 @@ interface LinearWorkspace {
 interface InterruptResult {
 	__interrupt__: true;
 	__decided__?: "approve" | "reject" | "edit";
+	__completed__?: boolean;
 	action_requests: Array<{
 		name: string;
 		args: Record<string, unknown>;
@ -143,10 +145,7 @@ function ApprovalCard({
 		edited_action?: { name: string; args: Record<string, unknown> };
 	}) => void;
 }) {
-	const [decided, setDecided] = useState<"approve" | "reject" | "edit" | null>(
-		interruptData.__decided__ ?? null
-	);
-	const [wasAlreadyDecided] = useState(() => interruptData.__decided__ != null);
+	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
 	const openHitlEditPanel = useSetAtom(openHitlEditPanelAtom);
 	const [pendingEdits, setPendingEdits] = useState<{ title: string; description: string } | null>(null);
@ -193,10 +192,11 @@ function ApprovalCard({
 	}, [args.title, args.description, selectedWorkspaceId, selectedTeamId, selectedStateId, selectedAssigneeId, selectedPriority, selectedLabelIds, pendingEdits]);

 	const handleApprove = useCallback(() => {
-		if (decided || isPanelOpen || !canApprove) return;
+		if (phase !== "pending") return;
+		if (isPanelOpen || !canApprove) return;
 		if (!allowedDecisions.includes("approve")) return;
 		const isEdited = pendingEdits !== null;
-		setDecided(isEdited ? "edit" : "approve");
+		setProcessing();
 		onDecision({
 			type: isEdited ? "edit" : "approve",
 			edited_action: {
@ -204,7 +204,7 @@ function ApprovalCard({
 				args: buildFinalArgs(),
 			},
 		});
-	}, [decided, isPanelOpen, canApprove, allowedDecisions, onDecision, interruptData, buildFinalArgs, pendingEdits]);
+	}, [phase, setProcessing, isPanelOpen, canApprove, allowedDecisions, onDecision, interruptData, buildFinalArgs, pendingEdits]);

 	useEffect(() => {
 		const handler = (e: KeyboardEvent) => {
@ -222,29 +222,29 @@ function ApprovalCard({
 			<div className="flex items-start justify-between px-5 pt-5 pb-4 select-none">
 				<div>
 					<p className="text-sm font-semibold text-foreground">
-						{decided === "reject"
+						{phase === "rejected"
 							? "Linear Issue Rejected"
-							: decided === "approve" || decided === "edit"
+							: phase === "processing" || phase === "complete"
 								? "Linear Issue Approved"
 								: "Create Linear Issue"}
 					</p>
-					{decided === "approve" || decided === "edit" ? (
-						wasAlreadyDecided ? (
-							<p className="text-xs text-muted-foreground mt-0.5">
-								{decided === "edit" ? "Issue created with your changes" : "Issue created"}
-							</p>
-						) : (
-							<TextShimmerLoader text={decided === "edit" ? "Creating issue with your changes" : "Creating issue"} size="sm" />
-						)
+					{phase === "processing" ? (
+						<TextShimmerLoader text={pendingEdits ? "Creating issue with your changes" : "Creating issue"} size="sm" />
+					) : phase === "complete" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							{pendingEdits ? "Issue created with your changes" : "Issue created"}
+						</p>
+					) : phase === "rejected" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							Issue creation was cancelled
+						</p>
 					) : (
 						<p className="text-xs text-muted-foreground mt-0.5">
-							{decided === "reject"
-								? "Issue creation was cancelled"
-								: "Requires your approval to proceed"}
+							Requires your approval to proceed
 						</p>
 					)}
 				</div>
-				{!decided && canEdit && (
+				{phase === "pending" && canEdit && (
 					<Button
 						size="sm"
 						variant="ghost"
@ -269,8 +269,8 @@ function ApprovalCard({
 				)}
 			</div>

-			{/* Context section */}
-			{!decided && (
+				{/* Context section — real pickers in pending */}
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-3 space-y-3 select-none">
@ -480,7 +480,7 @@ function ApprovalCard({
 			</div>

 			{/* Action buttons - only shown when pending */}
-			{!decided && (
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-3 flex items-center gap-2 select-none">
@ -502,7 +502,7 @@ function ApprovalCard({
 								className="rounded-lg text-muted-foreground"
 								disabled={isPanelOpen}
 								onClick={() => {
-									setDecided("reject");
+									setRejected();
 									onDecision({ type: "reject", message: "User rejected the action." });
 								}}
 							>
@ -582,7 +582,7 @@ export const CreateLinearIssueToolUI = makeAssistantToolUI<
 	CreateLinearIssueResult
 >({
 	toolName: "create_linear_issue",
-	render: function CreateLinearIssueUI({ args, result, status: _status }) {
+	render: function CreateLinearIssueUI({ args, result }) {
 		if (!result) return null;

 		if (isInterruptResult(result)) {
--- a/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/delete-linear-issue.tsx
@ -6,10 +6,12 @@ import { useCallback, useEffect, useState } from "react";
 import { Button } from "@/components/ui/button";
 import { Checkbox } from "@/components/ui/checkbox";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
+import { useHitlPhase } from "@/hooks/use-hitl-phase";

 interface InterruptResult {
 	__interrupt__: true;
 	__decided__?: "approve" | "reject";
+	__completed__?: boolean;
 	action_requests: Array<{
 		name: string;
 		args: Record<string, unknown>;
@ -128,21 +130,15 @@ function ApprovalCard({
 		edited_action?: { name: string; args: Record<string, unknown> };
 	}) => void;
 }) {
-	const actionArgs = interruptData.action_requests[0]?.args ?? {};
+	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
+	const [deleteFromKb, setDeleteFromKb] = useState(false);
+
 	const context = interruptData.context;
 	const issue = context?.issue;

-	const [decided, setDecided] = useState<"approve" | "reject" | null>(
-		interruptData.__decided__ ?? null
-	);
-	const [wasAlreadyDecided] = useState(() => interruptData.__decided__ != null);
-	const [deleteFromKb, setDeleteFromKb] = useState(
-		typeof actionArgs.delete_from_kb === "boolean" ? actionArgs.delete_from_kb : false
-	);
-
 	const handleApprove = useCallback(() => {
-		if (decided) return;
-		setDecided("approve");
+		if (phase !== "pending") return;
+		setProcessing();
 		onDecision({
 			type: "approve",
 			edited_action: {
@ -154,7 +150,7 @@ function ApprovalCard({
 				},
 			},
 		});
-	}, [decided, onDecision, interruptData, issue?.id, context?.workspace?.id, deleteFromKb]);
+	}, [phase, setProcessing, onDecision, interruptData, issue?.id, context?.workspace?.id, deleteFromKb]);

 	useEffect(() => {
 		const handler = (e: KeyboardEvent) => {
@ -172,38 +168,38 @@ function ApprovalCard({
 			<div className="flex items-start justify-between px-5 pt-5 pb-4 select-none">
 				<div>
 					<p className="text-sm font-semibold text-foreground">
-						{decided === "reject"
+						{phase === "rejected"
 							? "Linear Issue Deletion Rejected"
-							: decided === "approve"
+							: phase === "processing" || phase === "complete"
 								? "Linear Issue Deletion Approved"
 								: "Delete Linear Issue"}
 					</p>
-					{decided === "approve" ? (
-						wasAlreadyDecided ? (
-							<p className="text-xs text-muted-foreground mt-0.5">Issue deleted</p>
-						) : (
-							<TextShimmerLoader text="Deleting issue" size="sm" />
-						)
+				{phase === "processing" ? (
+						<TextShimmerLoader text="Deleting issue" size="sm" />
+					) : phase === "complete" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">Issue deleted</p>
+					) : phase === "rejected" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							Issue deletion was cancelled
+						</p>
 					) : (
 						<p className="text-xs text-muted-foreground mt-0.5">
-							{decided === "reject"
-								? "Issue deletion was cancelled"
-								: "Requires your approval to proceed"}
+							Requires your approval to proceed
 						</p>
 					)}
 				</div>
 			</div>

-			{/* Context section — workspace + issue info (read-only) */}
-			{!decided && (
+			{/* Context section — workspace + issue info (visible in pending, processing, complete) */}
+			{phase !== "rejected" && context && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-4 space-y-4 select-none">
-						{context?.error ? (
+						{context.error ? (
 							<p className="text-sm text-destructive">{context.error}</p>
 						) : (
 							<>
-								{context?.workspace && (
+								{context.workspace && (
 									<div className="space-y-2">
 										<p className="text-xs font-medium text-muted-foreground">Linear Account</p>
 										<div className="w-full rounded-md border border-input bg-muted/50 px-3 py-2 text-sm">
@ -232,7 +228,7 @@ function ApprovalCard({
 			)}

 			{/* delete_from_kb toggle */}
-			{!decided && (
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-4 select-none">
@ -255,7 +251,7 @@ function ApprovalCard({
 			)}

 			{/* Action buttons - only shown when pending */}
-			{!decided && (
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 				<div className="px-5 py-4 flex items-center gap-2 select-none">
@ -272,7 +268,7 @@ function ApprovalCard({
 							variant="ghost"
 							className="rounded-lg text-muted-foreground"
 							onClick={() => {
-								setDecided("reject");
+								setRejected();
 								onDecision({ type: "reject", message: "User rejected the action." });
 							}}
 						>
@ -371,7 +367,7 @@ export const DeleteLinearIssueToolUI = makeAssistantToolUI<
 	DeleteLinearIssueResult
 >({
 	toolName: "delete_linear_issue",
-	render: function DeleteLinearIssueUI({ result, status: _status }) {
+	render: function DeleteLinearIssueUI({ result }) {
 		if (!result) return null;

 		if (isInterruptResult(result)) {
@ -379,9 +375,10 @@ export const DeleteLinearIssueToolUI = makeAssistantToolUI<
 				<ApprovalCard
 					interruptData={result}
 					onDecision={(decision) => {
-						window.dispatchEvent(
-							new CustomEvent("hitl-decision", { detail: { decisions: [decision] } })
-						);
+						const event = new CustomEvent("hitl-decision", {
+							detail: { decisions: [decision] },
+						});
+						window.dispatchEvent(event);
 					}}
 				/>
 			);
--- a/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
+++ b/surfsense_web/components/tool-ui/linear/update-linear-issue.tsx
@ -16,6 +16,7 @@ import {
 import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { PlateEditor } from "@/components/editor/plate-editor";
 import { TextShimmerLoader } from "@/components/prompt-kit/loader";
+import { useHitlPhase } from "@/hooks/use-hitl-phase";
 import { openHitlEditPanelAtom } from "@/atoms/chat/hitl-edit-panel.atom";

 interface LinearLabel {
@ -47,6 +48,7 @@ interface LinearPriority {
 interface InterruptResult {
 	__interrupt__: true;
 	__decided__?: "approve" | "reject" | "edit";
+	__completed__?: boolean;
 	action_requests: Array<{
 		name: string;
 		args: Record<string, unknown>;
@ -147,9 +149,19 @@ function isAuthErrorResult(result: unknown): result is AuthErrorResult {
 }

 function ApprovalCard({
+	args,
 	interruptData,
 	onDecision,
 }: {
+	args: {
+		issue_ref: string;
+		new_title?: string;
+		new_description?: string;
+		new_state_name?: string;
+		new_assignee_email?: string;
+		new_priority?: number;
+		new_label_names?: string[];
+	};
 	interruptData: InterruptResult;
 	onDecision: (decision: {
 		type: "approve" | "reject" | "edit";
@ -157,6 +169,8 @@ function ApprovalCard({
 		edited_action?: { name: string; args: Record<string, unknown> };
 	}) => void;
 }) {
+	const { phase, setProcessing, setRejected } = useHitlPhase(interruptData);
+
 	const actionArgs = interruptData.action_requests[0]?.args ?? {};
 	const context = interruptData.context;
 	const team = context?.team;
@ -164,10 +178,10 @@ function ApprovalCard({
 	const issue = context?.issue;

 	const initialEditState = {
-		title: actionArgs.new_title ? String(actionArgs.new_title) : (issue?.title ?? ""),
+		title: actionArgs.new_title ? String(actionArgs.new_title) : (issue?.title ?? args.new_title ?? ""),
 		description: actionArgs.new_description
 			? String(actionArgs.new_description)
-			: (issue?.description ?? ""),
+			: (issue?.description ?? args.new_description ?? ""),
 		stateId: actionArgs.new_state_id
 			? String(actionArgs.new_state_id)
 			: (issue?.current_state?.id ?? "__none__"),
@ -183,10 +197,6 @@ function ApprovalCard({
 			: (issue?.current_labels?.map((l) => l.id) ?? []),
 	};

-	const [decided, setDecided] = useState<"approve" | "reject" | "edit" | null>(
-		interruptData.__decided__ ?? null
-	);
-	const [wasAlreadyDecided] = useState(() => interruptData.__decided__ != null);
 	const [isPanelOpen, setIsPanelOpen] = useState(false);
 	const [editedArgs, setEditedArgs] = useState(initialEditState);
 	const [hasPanelEdits, setHasPanelEdits] = useState(false);
@ -246,18 +256,19 @@ function ApprovalCard({
 	);

 	const hasProposedChanges =
-		actionArgs.new_title ||
-		actionArgs.new_description ||
+		actionArgs.new_title || args.new_title ||
+		actionArgs.new_description || args.new_description ||
 		proposedStateName ||
 		proposedAssigneeName ||
 		proposedPriorityLabel ||
 		proposedLabelObjects.length > 0;

 	const handleApprove = useCallback(() => {
-		if (decided || isPanelOpen) return;
+		if (phase !== "pending") return;
+		if (isPanelOpen) return;
 		if (!allowedDecisions.includes("approve")) return;
 		const isEdited = hasPanelEdits;
-		setDecided(isEdited ? "edit" : "approve");
+		setProcessing();
 		onDecision({
 			type: isEdited ? "edit" : "approve",
 			edited_action: {
@ -265,7 +276,7 @@ function ApprovalCard({
 				args: buildFinalArgs(),
 			},
 		});
-	}, [decided, isPanelOpen, allowedDecisions, onDecision, interruptData, buildFinalArgs, hasPanelEdits]);
+	}, [phase, setProcessing, isPanelOpen, allowedDecisions, onDecision, interruptData, buildFinalArgs, hasPanelEdits]);

 	useEffect(() => {
 		const handler = (e: KeyboardEvent) => {
@ -283,29 +294,29 @@ function ApprovalCard({
 			<div className="flex items-start justify-between px-5 pt-5 pb-4 select-none">
 				<div>
 					<p className="text-sm font-semibold text-foreground">
-						{decided === "reject"
+						{phase === "rejected"
 							? "Linear Issue Update Rejected"
-							: decided === "approve" || decided === "edit"
+							: phase === "processing" || phase === "complete"
 								? "Linear Issue Update Approved"
 								: "Update Linear Issue"}
 					</p>
-					{decided === "approve" || decided === "edit" ? (
-						wasAlreadyDecided ? (
-							<p className="text-xs text-muted-foreground mt-0.5">
-								{decided === "edit" ? "Issue updated with your changes" : "Issue updated"}
-							</p>
-						) : (
-							<TextShimmerLoader text={decided === "edit" ? "Updating issue with your changes" : "Updating issue"} size="sm" />
-						)
+					{phase === "processing" ? (
+						<TextShimmerLoader text={hasPanelEdits ? "Updating issue with your changes" : "Updating issue"} size="sm" />
+					) : phase === "complete" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							{hasPanelEdits ? "Issue updated with your changes" : "Issue updated"}
+						</p>
+					) : phase === "rejected" ? (
+						<p className="text-xs text-muted-foreground mt-0.5">
+							Issue update was cancelled
+						</p>
 					) : (
 						<p className="text-xs text-muted-foreground mt-0.5">
-							{decided === "reject"
-								? "Issue update was cancelled"
-								: "Requires your approval to proceed"}
+							Requires your approval to proceed
 						</p>
 					)}
 				</div>
-				{!decided && canEdit && (
+				{phase === "pending" && canEdit && (
 					<Button
 						size="sm"
 						variant="ghost"
@ -335,8 +346,8 @@ function ApprovalCard({
 				)}
 			</div>

-			{/* Context section — workspace + current issue (read-only) */}
-			{!decided && (
+				{/* Context section — workspace + current issue + pickers in pending */}
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-4 space-y-4 select-none">
@ -407,7 +418,6 @@ function ApprovalCard({
 									</div>
 								)}

-								{/* Editable context selects for state, assignee, priority, labels */}
 								{team && (
 									<>
 										<div className="space-y-2">
@ -530,10 +540,10 @@ function ApprovalCard({
 			<div className="px-5 pt-3">
 				{(hasProposedChanges || hasPanelEdits) ? (
 					<>
-						{(hasPanelEdits ? editedArgs.title : actionArgs.new_title) && (
-							<p className="text-sm font-medium text-foreground">{String(hasPanelEdits ? editedArgs.title : actionArgs.new_title)}</p>
+						{(hasPanelEdits ? editedArgs.title : (actionArgs.new_title ?? args.new_title)) && (
+							<p className="text-sm font-medium text-foreground">{String(hasPanelEdits ? editedArgs.title : (actionArgs.new_title ?? args.new_title))}</p>
 						)}
-						{(hasPanelEdits ? editedArgs.description : actionArgs.new_description) && (
+						{(hasPanelEdits ? editedArgs.description : (actionArgs.new_description ?? args.new_description)) && (
 							<div
 								className="max-h-[7rem] overflow-hidden text-sm"
 								style={{
@ -542,7 +552,7 @@ function ApprovalCard({
 								}}
 							>
 								<PlateEditor
-									markdown={String(hasPanelEdits ? editedArgs.description : actionArgs.new_description)}
+									markdown={String(hasPanelEdits ? editedArgs.description : (actionArgs.new_description ?? args.new_description))}
 									readOnly
 									preset="readonly"
 									editorVariant="none"
@ -591,7 +601,7 @@ function ApprovalCard({
 			</div>

 			{/* Action buttons - only shown when pending */}
-			{!decided && (
+			{phase === "pending" && (
 				<>
 					<div className="mx-5 h-px bg-border/50" />
 					<div className="px-5 py-4 flex items-center gap-2 select-none">
@ -613,7 +623,7 @@ function ApprovalCard({
 								className="rounded-lg text-muted-foreground"
 								disabled={isPanelOpen}
 								onClick={() => {
-									setDecided("reject");
+									setRejected();
 									onDecision({ type: "reject", message: "User rejected the action." });
 								}}
 							>
@ -717,12 +727,13 @@ export const UpdateLinearIssueToolUI = makeAssistantToolUI<
 	UpdateLinearIssueResult
 >({
 	toolName: "update_linear_issue",
-	render: function UpdateLinearIssueUI({ result, status: _status }) {
+	render: function UpdateLinearIssueUI({ args, result }) {
 		if (!result) return null;

 		if (isInterruptResult(result)) {
 			return (
 				<ApprovalCard
+					args={args}
 					interruptData={result}
 					onDecision={(decision) => {
 						window.dispatchEvent(