@vanillagreen/pi-qol 1.1.1 → 1.3.0

package/extensions/qol/editor.ts

@@ -0,0 +1,183 @@
+import { CustomEditor, Theme, type ExtensionContext, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth, type AutocompleteItem, type AutocompleteSuggestions, type EditorTheme, type TUI } from "@earendil-works/pi-tui";
+import { stripAnsi } from "./ansi.js";
+import { readCavemanBridge } from "./bridges.js";
+import { STATUS_KEY } from "./constants.js";
+import { statusText, styleImageChips } from "./images.js";
+import { newlineFallbackKey, settingBoolean } from "./settings.js";
+
+function styleAutocompleteHintItem(item: AutocompleteItem, theme: Theme): AutocompleteItem {
+	const label = stripAnsi(item.label || item.value);
+	const styled: AutocompleteItem = { ...item, label: theme.fg("accent", label) };
+	if (typeof item.description === "string" && item.description.length > 0) {
+		styled.description = theme.fg("text", stripAnsi(item.description));
+	}
+	return styled;
+}
+
+function styleSlashAutocompleteHints(suggestions: AutocompleteSuggestions | null, theme: Theme): AutocompleteSuggestions | null {
+	if (!suggestions || !suggestions.prefix.startsWith("/")) return suggestions;
+	return { ...suggestions, items: suggestions.items.map((item) => styleAutocompleteHintItem(item, theme)) };
+}
+
+export function installAutocompleteHintStyling(ctx: ExtensionContext): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.addAutocompleteProvider((current) => ({
+		async getSuggestions(lines, cursorLine, cursorCol, options) {
+			return styleSlashAutocompleteHints(await current.getSuggestions(lines, cursorLine, cursorCol, options), ctx.ui.theme);
+		},
+		applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+			return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+		},
+		shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+			return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+		},
+	}));
+}
+
+const QOL_ARGUMENT_COMPLETIONS: AutocompleteItem[] = [
+	{ value: "status", label: "status", description: "Show QOL status and current settings" },
+	{ value: "rename", label: "rename", description: "Generate a session name from the first user message" },
+	{ value: "notify-test", label: "notify-test", description: "Send a test QOL notification" },
+];
+
+const QOL_RENAME_ARGUMENT_COMPLETIONS: AutocompleteItem[] = [
+	{ value: "rename full", label: "rename full", description: "Generate a session name from the full conversation" },
+];
+
+export function getQolArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+	const query = prefix.trimStart().toLowerCase();
+	const items = query.startsWith("rename ") ? QOL_RENAME_ARGUMENT_COMPLETIONS : QOL_ARGUMENT_COMPLETIONS;
+	const filtered = items.filter((item) => item.value.toLowerCase().startsWith(query));
+	return filtered.length > 0 ? filtered : null;
+}
+
+const SESSION_SEARCH_ARGUMENT_COMPLETIONS: AutocompleteItem[] = [
+	{ value: "refresh", label: "refresh", description: "Refresh the session search index" },
+];
+
+export function getSessionSearchArgumentCompletions(prefix: string): AutocompleteItem[] | null {
+	const query = prefix.trimStart().toLowerCase();
+	const filtered = SESSION_SEARCH_ARGUMENT_COMPLETIONS.filter((item) => item.value.toLowerCase().startsWith(query) || (item.label ?? item.value).toLowerCase().startsWith(query));
+	return filtered.length > 0 ? filtered : null;
+}
+
+function handleQolEditorInput(editor: CustomEditor, ctx: ExtensionContext, data: string): void {
+	if (matchesKey(data, "alt+c")) {
+		const caveman = readCavemanBridge();
+		if (caveman?.cycleMode) {
+			const next = caveman.cycleMode(ctx.cwd);
+			if (typeof next === "string") {
+				try { ctx.ui.notify(next === "off" ? "Caveman off." : `Caveman ${next} active.`, "info"); } catch { /* notify is best-effort */ }
+			}
+			return;
+		}
+	}
+	const fallback = newlineFallbackKey(ctx.cwd);
+	const newlineEnabled = settingBoolean("newlineOnShiftEnter", true, ctx.cwd);
+	const isShiftEnter = matchesKey(data, "shift+enter") || matchesKey(data, "shift+return");
+	const isFallback = fallback !== "none" && matchesKey(data, fallback);
+	CustomEditor.prototype.handleInput.call(editor, newlineEnabled && (isShiftEnter || isFallback) ? "\n" : data);
+}
+
+/// Push the latest attachment-count status only when it actually changes.
+/// Called from render() so we follow the rainbow-editor pattern (pull from
+/// render, don't push from every keystroke) and avoid the per-keystroke
+/// setStatus side effect that previously contributed to resize/input races.
+function syncQolEditorStatus(
+	ctx: ExtensionContext,
+	text: string,
+	cache: { last?: string },
+): void {
+	const next = statusText(ctx, text);
+	if (next === cache.last) return;
+	cache.last = next;
+	try {
+		ctx.ui.setStatus(STATUS_KEY, next);
+	} catch {
+		// best-effort visual; don't let a status push break render
+	}
+}
+
+export class QolEditor extends CustomEditor {
+	private readonly statusCache: { last?: string } = {};
+
+	constructor(
+		tui: TUI,
+		editorTheme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private readonly ctx: ExtensionContext,
+	) {
+		super(tui, editorTheme, keybindings);
+	}
+
+	handleInput(data: string): void {
+		handleQolEditorInput(this, this.ctx, data);
+	}
+
+	render(width: number): string[] {
+		syncQolEditorStatus(this.ctx, this.getText(), this.statusCache);
+		return super.render(width).map((line) => truncateToWidth(styleImageChips(line, this.ctx.cwd, this.ctx.ui.theme), width, ""));
+	}
+}
+
+function isEditorBorderLine(line: string): boolean {
+	const visible = stripAnsi(line).trim();
+	return visible.length > 0 && /^[─━╭╮╰╯┌┐└┘]+$/.test(visible);
+}
+
+export class QolCompactPromptEditor extends CustomEditor {
+	private readonly statusCache: { last?: string } = {};
+
+	constructor(
+		tui: TUI,
+		editorTheme: EditorTheme,
+		keybindings: KeybindingsManager,
+		private readonly inputBottomPaddingLines: number,
+		private readonly ctx: ExtensionContext,
+	) {
+		super(tui, editorTheme, keybindings, { paddingX: 0 });
+	}
+
+	handleInput(data: string): void {
+		handleQolEditorInput(this, this.ctx, data);
+	}
+
+	render(width: number): string[] {
+		syncQolEditorStatus(this.ctx, this.getText(), this.statusCache);
+		const prompt = this.borderColor("π");
+		const prefix = `${prompt} `;
+		const prefixWidth = visibleWidth("π ");
+		const continuationPrefix = " ".repeat(prefixWidth);
+		const innerWidth = Math.max(1, width - prefixWidth);
+		const rendered = super.render(innerWidth);
+
+		const inputLines: string[] = [];
+		let completionLines: string[] = [];
+		for (let index = 1; index < rendered.length; index++) {
+			const line = rendered[index] ?? "";
+			if (isEditorBorderLine(line)) {
+				completionLines = rendered.slice(index + 1);
+				break;
+			}
+			inputLines.push(line);
+		}
+
+		const lines = (inputLines.length > 0 ? inputLines : [""]).map((line, index) => {
+			const linePrefix = index === 0 ? prefix : continuationPrefix;
+			const content = styleImageChips(line, this.ctx.cwd, this.ctx.ui.theme);
+			return truncateToWidth(linePrefix + content, width, "");
+		});
+		for (let index = 0; index < this.inputBottomPaddingLines; index++) lines.push("");
+		for (const line of completionLines) lines.push(truncateToWidth(`${this.ctx.ui.theme.fg("dim", continuationPrefix)}${line}`, width, ""));
+		return lines;
+	}
+}
+
+export function currentEditorText(ctx: ExtensionContext): string {
+	try {
+		return ctx.ui.getEditorText?.() ?? "";
+	} catch {
+		return "";
+	}
+}

package/extensions/qol/handoff.ts

@@ -0,0 +1,109 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { complete, type Message } from "@earendil-works/pi-ai";
+import { BorderedLoader, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { acquireVstackModalLock } from "./bridges.js";
+import { serializeMessagesForSummary } from "./compaction.js";
+import { HANDOFF_SYSTEM_PROMPT } from "./constants.js";
+import { settingBoolean } from "./settings.js";
+
+export async function runHandoff(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify("handoff requires interactive mode", "error");
+		return;
+	}
+
+	if (!ctx.model) {
+		ctx.ui.notify("No model selected", "error");
+		return;
+	}
+
+	const goal = args.trim();
+	if (!goal) {
+		ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+		return;
+	}
+
+	const built = (ctx.sessionManager as any).buildSessionContext?.();
+	const messages = Array.isArray(built?.messages) ? built.messages as AgentMessage[] : [];
+
+	if (messages.length === 0) {
+		ctx.ui.notify("No conversation to hand off", "error");
+		return;
+	}
+
+	const conversationText = serializeMessagesForSummary(messages);
+	const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+	const releaseModalLock = acquireVstackModalLock();
+	let result: string | null = null;
+	try {
+	result = await ctx.ui.custom<string | null>((tui: any, theme: any, _kb: any, done: (value: string | null) => void) => {
+		const loader = new BorderedLoader(tui, theme, "Generating handoff prompt...");
+		loader.onAbort = () => done(null);
+
+		const doGenerate = async () => {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+			if (!auth.ok || !auth.apiKey) {
+				throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+			}
+
+			const userMessage: Message = {
+				role: "user",
+				content: [
+					{
+						type: "text",
+						text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+					},
+				],
+				timestamp: Date.now(),
+			};
+
+			const response = await complete(
+				ctx.model!,
+				{ systemPrompt: HANDOFF_SYSTEM_PROMPT, messages: [userMessage] },
+				{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
+			);
+
+			if (response.stopReason === "aborted") return null;
+			return response.content
+				.filter((content): content is { type: "text"; text: string } => content.type === "text")
+				.map((content) => content.text)
+				.join("\n");
+		};
+
+		doGenerate()
+			.then(done)
+			.catch((error) => {
+				console.error("Handoff generation failed:", error);
+				done(null);
+			});
+
+		return loader;
+	});
+	} finally {
+		releaseModalLock();
+	}
+
+	if (result === null) {
+		ctx.ui.notify("Cancelled", "info");
+		return;
+	}
+
+	const prompt = settingBoolean("handoffReviewPrompt", true, ctx.cwd) ? await ctx.ui.editor("Edit handoff prompt", result) : result;
+	if (prompt === undefined) {
+		ctx.ui.notify("Cancelled", "info");
+		return;
+	}
+
+	const newSessionResult = await ctx.newSession({
+		parentSession: currentSessionFile,
+		withSession: async (replacementCtx: any) => {
+			replacementCtx.ui.setEditorText(prompt);
+			replacementCtx.ui.notify("Handoff ready. Submit when ready.", "info");
+		},
+	});
+
+	if (newSessionResult.cancelled) {
+		ctx.ui.notify("New session cancelled", "info");
+	}
+}

package/extensions/qol/images.ts

@@ -0,0 +1,123 @@
+import { existsSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { applyVisibleReplacements, buildVisibleMap, type VisibleReplacement } from "./ansi.js";
+import { IMAGE_EXTENSIONS, IMAGE_PATH_PATTERN } from "./constants.js";
+import { expandHome, settingBoolean } from "./settings.js";
+
+function stripAtPrefix(path: string): string {
+	return path.startsWith("@") ? path.slice(1) : path;
+}
+
+export function resolveMaybeImagePath(path: string, cwd: string): string | undefined {
+	const clean = stripAtPrefix(path);
+	const expanded = expandHome(clean);
+	const resolved = expanded.startsWith("/") ? expanded : resolve(cwd, expanded);
+	const lower = resolved.toLowerCase();
+	const dot = lower.lastIndexOf(".");
+	if (dot < 0 || !IMAGE_EXTENSIONS.has(lower.slice(dot))) return undefined;
+	if (!existsSync(resolved)) return undefined;
+	return resolved;
+}
+
+function imagePathLabels(text: string, cwd: string): string[] {
+	const seen = new Set<string>();
+	for (const match of text.matchAll(IMAGE_PATH_PATTERN)) {
+		const resolved = resolveMaybeImagePath(match[2] ?? "", cwd);
+		if (resolved) seen.add(`Image ${basename(resolved)}`);
+	}
+	return [...seen].sort();
+}
+
+function mimeTypeForPath(path: string): string {
+	const lower = path.toLowerCase();
+	if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+	if (lower.endsWith(".gif")) return "image/gif";
+	if (lower.endsWith(".webp")) return "image/webp";
+	if (lower.endsWith(".bmp")) return "image/bmp";
+	if (lower.endsWith(".tif") || lower.endsWith(".tiff")) return "image/tiff";
+	if (lower.endsWith(".heic")) return "image/heic";
+	if (lower.endsWith(".heif")) return "image/heif";
+	return "image/png";
+}
+
+export function imageContentForPath(path: string): { type: "image"; data: string; mimeType: string } | undefined {
+	try {
+		return { data: readFileSync(path).toString("base64"), mimeType: mimeTypeForPath(path), type: "image" };
+	} catch {
+		return undefined;
+	}
+}
+
+export function attachmentLabels(text: string, cwd = process.cwd()): string[] {
+	const seen = new Set<string>();
+	for (const match of text.matchAll(/\[Image\s+#(\d+)\]/gi)) {
+		seen.add(`Image #${match[1]}`);
+	}
+	for (const label of imagePathLabels(text, cwd)) seen.add(label);
+	return [...seen].sort((a, b) => Number(a.replace(/\D/g, "")) - Number(b.replace(/\D/g, "")) || a.localeCompare(b));
+}
+
+function chip(label: string, theme?: Theme): string {
+	const text = ` ${label} `;
+	if (theme) return theme.fg("accent", theme.inverse(text));
+	return `[${label}]`;
+}
+
+function imageChipReplacements(visibleText: string, cwd: string, theme?: Theme): VisibleReplacement[] {
+	const replacements: VisibleReplacement[] = [];
+
+	for (const match of visibleText.matchAll(/\[Image\s+#(\d+)\]/gi)) {
+		const start = match.index ?? 0;
+		replacements.push({
+			start,
+			end: start + match[0].length,
+			text: chip(`Image #${match[1]}`, theme),
+		});
+	}
+
+	let imageIndex = 0;
+	for (const match of visibleText.matchAll(IMAGE_PATH_PATTERN)) {
+		const prefix = match[1] ?? "";
+		const rawPath = match[2] ?? "";
+		const resolved = resolveMaybeImagePath(rawPath, cwd);
+		if (!resolved) continue;
+
+		imageIndex += 1;
+		const start = (match.index ?? 0) + prefix.length;
+		replacements.push({
+			start,
+			end: start + rawPath.length,
+			text: chip(`Image ${imageIndex}`, theme),
+		});
+	}
+
+	return replacements;
+}
+
+export function styleImageChips(line: string, cwd: string, theme?: Theme): string {
+	if (!settingBoolean("showImageChips", true, cwd)) return line;
+	const map = buildVisibleMap(line);
+	const replacements = imageChipReplacements(map.text, cwd, theme);
+	return replacements.length === 0 ? line : applyVisibleReplacements(line, map, replacements);
+}
+
+export function statusText(ctx: ExtensionContext, text: string): string | undefined {
+	if (!settingBoolean("showAttachmentCountInStatus", true, ctx.cwd)) return undefined;
+	const count = attachmentLabels(text, ctx.cwd).length;
+	return count > 0 ? `images:${count}` : undefined;
+}
+
+/// Resolve every image-path-shaped substring in submitted text to an
+/// absolute file path. Used by the `input` event to replace the previous
+/// approach of mutating the editor buffer to `[Image #N]` aliases via a
+/// 250ms polling timer (which raced with resize/input handling).
+export function resolveSubmittedImagePaths(text: string, cwd: string): string[] {
+	const paths = new Set<string>();
+	for (const match of text.matchAll(IMAGE_PATH_PATTERN)) {
+		const resolved = resolveMaybeImagePath(match[2] ?? "", cwd);
+		if (resolved) paths.add(resolved);
+	}
+	return [...paths];
+}
+

package/extensions/qol/notifications.ts

@@ -0,0 +1,269 @@
+import { execFile, execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_NOTIFICATION_BODY_MAX_CHARS,
+	DEFAULT_NOTIFICATION_COOLDOWN_SECONDS,
+	DEFAULT_NOTIFICATION_TITLE,
+	DEFAULT_TMUX_MESSAGE_DURATION_MS,
+	QUESTION_NOTIFY_DEDUP_MS,
+} from "./constants.js";
+import { settingBoolean, settingNumber, settingString } from "./settings.js";
+import type { QuestionOpenedEventLike, QuestionRequestLike } from "./bridges.js";
+
+export type QolNotificationKind = "ready" | "direction" | "question" | "task-complete" | "critical" | "test";
+export type QolNotificationLevel = "info" | "warning" | "error";
+
+export interface QolNotificationService {
+	notifyQuestionOpened(ctx: ExtensionContext | undefined, event: QuestionOpenedEventLike): boolean;
+}
+
+const lastNotificationAt = new Map<string, number>();
+const lastQuestionNotificationAt = new Map<string, number>();
+let tmuxMarkedTarget: string | undefined;
+let tmuxOriginalWindowName: string | undefined;
+let tmuxWindowMarkTimer: ReturnType<typeof setTimeout> | undefined;
+
+export function sanitizeNotificationPart(input: string, maxChars = DEFAULT_NOTIFICATION_BODY_MAX_CHARS): string {
+	const cleaned = input
+		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return cleaned.length > maxChars ? `${cleaned.slice(0, Math.max(0, maxChars - 1))}…` : cleaned;
+}
+
+function windowsToastScript(title: string, body: string): string {
+	const escapedTitle = title.replace(/'/g, "''");
+	const escapedBody = body.replace(/'/g, "''");
+	const type = "Windows.UI.Notifications";
+	const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`;
+	const template = `[${type}.ToastTemplateType]::ToastText02`;
+	const toast = `[${type}.ToastNotification]::new($xml)`;
+	return [
+		`${mgr} > $null`,
+		`$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`,
+		`$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${escapedTitle}')) > $null`,
+		`$xml.GetElementsByTagName('text')[1].AppendChild($xml.CreateTextNode('${escapedBody}')) > $null`,
+		`[${type}.ToastNotificationManager]::CreateToastNotifier('${escapedTitle}').Show(${toast})`,
+	].join("; ");
+}
+
+function tmuxPassthrough(sequence: string): string {
+	return `\x1bPtmux;${sequence.replace(/\x1b/g, "\x1b\x1b")}\x1b\\`;
+}
+
+function sourcePaneTty(): string | undefined {
+	try {
+		if (!process.env.TMUX_PANE) return undefined;
+		const tty = execFileSync("tmux", ["display-message", "-p", "-t", process.env.TMUX_PANE, "#{pane_tty}"], { encoding: "utf8" }).trim();
+		return tty || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function sourceTmuxSession(): string | undefined {
+	try {
+		if (!process.env.TMUX_PANE) return undefined;
+		const session = execFileSync("tmux", ["display-message", "-p", "-t", process.env.TMUX_PANE, "#{session_name}"], { encoding: "utf8" }).trim();
+		return session || undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function sourceTmuxWindowActive(): boolean {
+	try {
+		if (!process.env.TMUX_PANE) return false;
+		const active = execFileSync("tmux", ["display-message", "-p", "-t", process.env.TMUX_PANE, "#{window_active}"], { encoding: "utf8" }).trim();
+		return active === "1";
+	} catch {
+		return false;
+	}
+}
+
+function tmuxClientTtys(): string[] {
+	try {
+		if (!process.env.TMUX) return [];
+		const session = sourceTmuxSession();
+		const args = ["list-clients", "-F", "#{client_tty}"];
+		if (session) args.splice(1, 0, "-t", session);
+		const output = execFileSync("tmux", args, { encoding: "utf8" });
+		return [...new Set(output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean))];
+	} catch {
+		return [];
+	}
+}
+
+function writeRawToPaths(paths: string[], output: string): boolean {
+	let wrote = false;
+	for (const path of paths) {
+		try {
+			writeFileSync(path, output, "utf8");
+			wrote = true;
+		} catch {
+			// Try remaining paths.
+		}
+	}
+	return wrote;
+}
+
+function writeToTerminal(output: string): void {
+	const tty = sourcePaneTty();
+	try {
+		writeFileSync(tty ?? "/dev/tty", output, "utf8");
+		return;
+	} catch {
+		// Fall through to stdout best-effort.
+	}
+	try {
+		if (process.stdout.isTTY) process.stdout.write(output);
+	} catch {
+		// Notification best-effort only.
+	}
+}
+
+function writeTerminalSequence(sequence: string, cwd?: string): void {
+	if (process.env.TMUX && settingBoolean("notification.tmuxNativeClientTty", true, cwd)) {
+		// Inactive tmux windows do not forward arbitrary OSC output to the terminal.
+		// Send native terminal notifications straight to attached tmux client TTYs,
+		// while BEL still goes through the source pane so tmux marks the right tab.
+		if (writeRawToPaths(tmuxClientTtys(), sequence)) return;
+	}
+	const output = process.env.TMUX && settingBoolean("notification.tmuxPassthrough", true, cwd) ? tmuxPassthrough(sequence) : sequence;
+	writeToTerminal(output);
+}
+
+function writeTerminalBell(): void {
+	// Match Claude-style hooks: resolve the source pane TTY and write raw BEL there.
+	// This lets tmux set window_bell_flag for the correct source window.
+	writeToTerminal("\x07");
+}
+
+function notifyOSC777(title: string, body: string, cwd?: string): void {
+	writeTerminalSequence(`\x1b]777;notify;${title};${body}\x07`, cwd);
+}
+
+function notifyOSC99(title: string, body: string, cwd?: string): void {
+	writeTerminalSequence(`\x1b]99;i=1:d=0;${title}\x1b\\`, cwd);
+	writeTerminalSequence(`\x1b]99;i=1:p=body;${body}\x1b\\`, cwd);
+}
+
+function notifyWindows(title: string, body: string): void {
+	execFile("powershell.exe", ["-NoProfile", "-Command", windowsToastScript(title, body)], () => undefined);
+}
+
+function notifyNativeTerminal(title: string, body: string, cwd?: string): void {
+	const protocol = settingString("notification.oscProtocol", "auto", cwd);
+	if (process.env.WT_SESSION) {
+		notifyWindows(title, body);
+		return;
+	}
+	if (protocol === "off") return;
+	if (protocol === "osc99" || (protocol === "auto" && process.env.KITTY_WINDOW_ID)) {
+		notifyOSC99(title, body, cwd);
+		return;
+	}
+	notifyOSC777(title, body, cwd);
+}
+
+function notifyTmux(title: string, body: string, cwd?: string): void {
+	if (!process.env.TMUX && !process.env.TMUX_PANE) return;
+	const duration = Math.max(500, Math.floor(settingNumber("notification.tmuxMessageDurationMs", DEFAULT_TMUX_MESSAGE_DURATION_MS, cwd)));
+	const message = `${title}: ${body}`;
+	const args = ["display-message", "-d", String(duration)];
+	if (process.env.TMUX_PANE) args.push("-t", process.env.TMUX_PANE);
+	args.push(message);
+	execFile("tmux", args, () => undefined);
+}
+
+export function clearTmuxWindowMark(): void {
+	if (tmuxWindowMarkTimer) clearTimeout(tmuxWindowMarkTimer);
+	tmuxWindowMarkTimer = undefined;
+	const target = tmuxMarkedTarget;
+	const original = tmuxOriginalWindowName;
+	tmuxMarkedTarget = undefined;
+	tmuxOriginalWindowName = undefined;
+	if (!target || !original) return;
+	execFile("tmux", ["rename-window", "-t", target, original], () => undefined);
+}
+
+function markTmuxWindow(cwd?: string): void {
+	if (!settingBoolean("notification.tmuxWindowMark", false, cwd)) return;
+	if (!process.env.TMUX || !process.env.TMUX_PANE) return;
+	const mark = sanitizeNotificationPart(settingString("notification.tmuxWindowMarkText", "!", cwd), 12) || "!";
+	const prefix = `${mark} `;
+	execFile("tmux", ["display-message", "-p", "-t", process.env.TMUX_PANE, "#{session_name}:#{window_index}"], (targetError, targetStdout) => {
+		if (targetError) return;
+		const target = targetStdout.trim();
+		if (!target) return;
+		execFile("tmux", ["display-message", "-p", "-t", process.env.TMUX_PANE!, "#W"], (nameError, nameStdout) => {
+			if (nameError) return;
+			const current = nameStdout.replace(/\r?\n$/, "");
+			if (!current) return;
+			const original = current.startsWith(prefix) ? current.slice(prefix.length) : current;
+			if (!tmuxMarkedTarget || tmuxMarkedTarget !== target) {
+				tmuxMarkedTarget = target;
+				tmuxOriginalWindowName = original;
+			}
+			if (!current.startsWith(prefix)) execFile("tmux", ["rename-window", "-t", target, `${prefix}${current}`], () => undefined);
+			const duration = Math.max(0, Math.floor(settingNumber("notification.tmuxWindowMarkDurationMs", 0, cwd)));
+			if (tmuxWindowMarkTimer) clearTimeout(tmuxWindowMarkTimer);
+			if (duration > 0) {
+				tmuxWindowMarkTimer = setTimeout(clearTmuxWindowMark, duration);
+				tmuxWindowMarkTimer.unref?.();
+			}
+		});
+	});
+}
+
+function notificationEnabledFor(kind: QolNotificationKind, cwd?: string): boolean {
+	if (!settingBoolean("notification.enabled", true, cwd)) return false;
+	switch (kind) {
+		case "ready": return settingBoolean("notification.onAgentReady", true, cwd);
+		case "direction": return settingBoolean("notification.onDirectionNeeded", true, cwd);
+		case "question": return settingBoolean("notification.onQuestion", true, cwd);
+		case "task-complete": return settingBoolean("notification.onTaskComplete", true, cwd);
+		case "critical": return settingBoolean("notification.onCritical", true, cwd);
+		case "test": return true;
+	}
+}
+
+export function sendQolNotification(ctx: ExtensionContext | undefined, kind: QolNotificationKind, body: string, level: QolNotificationLevel = "info", key: string = kind): void {
+	const cwd = ctx?.cwd;
+	if (ctx && !ctx.hasUI) return;
+	if (!notificationEnabledFor(kind, cwd)) return;
+	const cooldownMs = Math.max(0, settingNumber("notification.cooldownSeconds", DEFAULT_NOTIFICATION_COOLDOWN_SECONDS, cwd) * 1000);
+	const now = Date.now();
+	const last = lastNotificationAt.get(key) ?? 0;
+	if (cooldownMs > 0 && now - last < cooldownMs) return;
+	lastNotificationAt.set(key, now);
+
+	const title = sanitizeNotificationPart(settingString("notification.title", DEFAULT_NOTIFICATION_TITLE, cwd), 80) || DEFAULT_NOTIFICATION_TITLE;
+	const text = sanitizeNotificationPart(body, Math.max(40, Math.floor(settingNumber("notification.bodyMaxChars", DEFAULT_NOTIFICATION_BODY_MAX_CHARS, cwd))));
+	const tmuxWindowActive = sourceTmuxWindowActive();
+	if (settingBoolean("notification.bell", true, cwd) && (!tmuxWindowActive || settingBoolean("notification.bellWhenActive", false, cwd))) writeTerminalBell();
+	if (settingBoolean("notification.native", true, cwd)) notifyNativeTerminal(title, text, cwd);
+	if (!tmuxWindowActive) markTmuxWindow(cwd);
+	if (settingBoolean("notification.tmux", false, cwd)) notifyTmux(title, text, cwd);
+	if (ctx?.hasUI && settingBoolean("notification.piUi", false, cwd)) ctx.ui.notify(text, level);
+}
+
+function questionNotificationTitle(request?: QuestionRequestLike): string {
+	if (typeof request?.header === "string" && request.header.trim()) return request.header.trim();
+	if (typeof request?.question === "string" && request.question.trim()) return request.question.trim();
+	return "Question";
+}
+
+export function notifyQuestionOpened(ctx: ExtensionContext | undefined, event: QuestionOpenedEventLike, keyPrefix = "question"): void {
+	const title = questionNotificationTitle(event.request);
+	const key = `${keyPrefix}:${event.requestId ?? title}`;
+	const now = Date.now();
+	const last = lastQuestionNotificationAt.get(key) ?? 0;
+	if (now - last < QUESTION_NOTIFY_DEDUP_MS) return;
+	lastQuestionNotificationAt.set(key, now);
+	for (const [storedKey, timestamp] of lastQuestionNotificationAt) {
+		if (now - timestamp > 60_000) lastQuestionNotificationAt.delete(storedKey);
+	}
+	sendQolNotification(ctx, "question", `Input required: ${title}`, "warning", key);
+}