Add support for OSC777 (Send Notification)

[carlos-zamora]

Summary of the Pull Request

targets #20010

This adds support for the OSC 777 ; notify ; title ; body ST sequence. This allows client applications to send a notification to the Terminal. When this notification is clicked, it summons the terminal window that sent it.

Validation Steps Performed

# in PowerShell. Terminal should not be focused.
sleep 2; Write-Output "`e]777;notify;Hello;This is a notification`a"

PR Checklist

• Closes Send Desktop Notification via VT Sequence (OSC777) #7718
• Documentation updated
• Schema updated (if necessary)

Heavily based on #19938
Co-authored by @zadjii-msft

The base branch was changed.

[DHowett]

wait, this seems wrong. it's not "Activity," is it?

[carlos-zamora]

Hmm... I think this one's fine, actually. It's all used here:

terminal/src/cascadia/TerminalApp/TabManagement.cpp

Lines 1226 to 1266 in fcaf3da

	void TerminalPage::_SendDesktopNotification(const winrt::hstring& tabTitle, const winrt::hstring& body, const winrt::com_ptr<Tab>& tab, const winrt::TerminalApp::IPaneContent& content)
	{
	// Don't send a notification if the window is focused and the requesting
	// pane is the active pane. The user is already looking at it.
	if (_activated && tab == _GetFocusedTabImpl())
	{
	if (const auto activePane{ tab->GetActivePane() })
	{
	if (activePane->GetContent() == content)
	{
	return;
	}
	}
	}
	// Build the notification message.
	// If a custom body is provided (e.g. from OSC 777), use the title/body directly.
	// Otherwise, build the standard tab-activity notification message.
	winrt::hstring notificationTitle;
	winrt::hstring message;
	if (!body.empty())
	{
	notificationTitle = tabTitle;
	message = body;
	}
	else
	{
	// Use the window name if available for context; otherwise just use the tab title.
	// Use the raw WindowName (not WindowNameForDisplay) so we don't include
	// the "<unnamed window>" placeholder in the notification body.
	const auto windowName = _WindowProperties ? _WindowProperties.WindowName() : winrt::hstring{};
	if (!windowName.empty())
	{
	message = RS_fmt(L"NotificationMessage_TabActivityInWindow", std::wstring_view{ tabTitle }, std::wstring_view{ windowName });
	}
	else
	{
	message = RS_fmt(L"NotificationMessage_TabActivity", std::wstring_view{ tabTitle });
	}
	notificationTitle = CascadiaSettings::ApplicationDisplayName();
	}

So, if OSC777 includes a body, we use the body & title from the sequence.
Otherwise, we fall back to these resources to say a generic "Activity in tab X".

Open to suggestions.

[DHowett]

qq: why does this need a public class type of its own? It's an implementation detail used only inside TerminalApp to talk to TerminalApp

[carlos-zamora]

Really just because we're using...

//  IPaneContent.idl
event Windows.Foundation.TypedEventHandler<IPaneContent, NotificationEventArgs> NotificationRequested;

I could update it to using a delegate so that we don't have a new public class type and we just pass the payload directly instead. Deciding against that in this PR because (1) it's a different style from the other ones in this file and (2) #20014 also uses this system to pass the payload up.

That said, I'm open to doing that as a follow-up once both of these merge. I think it's worth it and it looks nicer.

To get an idea of what it would look like:

// IPaneContent.idl
delegate void NotificationRequestedHandler(String title, String body);

interface IPaneContent
{
   event NotificationRequestedHandler NotificationRequested;
}

[carlos-zamora]

Feedback from Bug Bash (5/5)

• should be disabled by default

@DHowett Got a reason why? Is it that we just don't want applications to spam the user with notifications?

[carlos-zamora]

Updated default to false.

Validated that this works. Can be tested using:

Write-Host "$([char]27)]777;notify;Title;Message$([char]27)\"