@narumitw/pi-caffeinate 0.49.3 → 0.49.5

package/src/caffeinate.ts

@@ -5,6 +5,13 @@ import type {
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import {
+	type DbusScreenSaverClient,
+	type DbusScreenSaverFactory,
+	defaultDbusScreenSaverFactory,
+	INHIBIT_REASON,
+	SCREENSAVER_BUS_NAME,
+} from "./dbus-inhibit.js";
 import { startInhibitorProcess, stopInhibitorProcess } from "./inhibitor-process.js";
 import { formatMode, getInhibitorCommand, type InhibitorCommand } from "./inhibitors.js";
 import {
@@ -41,11 +48,27 @@ const MODE_OPTIONS = {
 type CommandAction = "menu" | "help" | "status" | "mode" | "sleep" | "display" | "stop";
 type CommandContext = ExtensionCommandContext;
 
+interface CaffeinateOptions {
+	dbusFactory?: DbusScreenSaverFactory;
+}
+
+interface PendingDbusStart {
+	token: number;
+	controller: AbortController;
+	client?: DbusScreenSaverClient;
+}
+
 interface CaffeinateState {
 	process?: ChildProcess;
+	dbus?: DbusScreenSaverClient;
+	currentSession?: { generation: number; ctx: ExtensionContext };
+	dbusCleanup?: Promise<void>;
+	pendingDbus?: PendingDbusStart;
 	startedAt?: number;
 	command?: InhibitorCommand;
 	lastError?: string;
+	inhibitWarning?: string;
+	inhibitorStarting: boolean;
 	activeTurns: number;
 	available: boolean;
 	disabled: boolean;
@@ -62,6 +85,7 @@ interface CaffeinateState {
 const state: CaffeinateState = {
 	activeTurns: 0,
 	available: true,
+	inhibitorStarting: false,
 	disabled: isDisabled(),
 	mode: DEFAULT_MODE,
 	quiet: false,
@@ -71,9 +95,14 @@ const state: CaffeinateState = {
 	menuController: new AbortController(),
 };
 
-export default function caffeinate(pi: ExtensionAPI) {
+let dbusFactory = defaultDbusScreenSaverFactory;
+let inhibitSequence = 0;
+
+export default function caffeinate(pi: ExtensionAPI, options: CaffeinateOptions = {}) {
+	dbusFactory = options.dbusFactory ?? defaultDbusScreenSaverFactory;
 	pi.on("session_start", async (_event, ctx) => {
 		const generation = ++state.sessionGeneration;
+		state.currentSession = { generation, ctx };
 		replaceMenuController("Caffeinate session replaced");
 		state.iconWarningShown = false;
 		state.settingsNotice = undefined;
@@ -88,24 +117,28 @@ export default function caffeinate(pi: ExtensionAPI) {
 		await ensureSettingsLoaded(ctx, generation);
 		if (generation !== state.sessionGeneration) return;
 		state.activeTurns += 1;
-		startInhibitor(ctx, { notify: !state.quiet });
+		await startInhibitor(ctx, generation, { notify: !state.quiet });
 	});
 
-	pi.on("agent_end", (_event, ctx) => {
+	pi.on("agent_end", async (_event, ctx) => {
+		const generation = state.sessionGeneration;
 		state.activeTurns = Math.max(0, state.activeTurns - 1);
 		if (state.activeTurns === 0) {
-			stopInhibitor(ctx, "agent finished", { notify: !state.quiet });
+			await stopInhibitor(ctx, "agent finished", { notify: !state.quiet });
 		}
+		if (generation !== state.sessionGeneration) return;
 		updateStatus(ctx);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
-		state.sessionGeneration += 1;
+		const generation = ++state.sessionGeneration;
+		state.currentSession = undefined;
 		state.menuController.abort(new DOMException("Caffeinate session shut down", "AbortError"));
 		state.activeTurns = 0;
-		stopInhibitor(ctx, "session shutdown", { notify: false });
-		ctx.ui.setStatus(STATUS_KEY, undefined);
+		await stopInhibitor(ctx, "session shutdown", { notify: false });
 		await modeOperationQueue;
+		if (generation !== state.sessionGeneration) return;
+		ctx.ui.setStatus(STATUS_KEY, undefined);
 	});
 
 	pi.registerCommand("caffeinate", {
@@ -147,7 +180,7 @@ async function handleCaffeinateCommand(args: string, ctx: CommandContext, genera
 			await setMode(ctx, "display", generation);
 			return;
 		case "stop":
-			stopCaffeinate(ctx, "manual stop");
+			await stopCaffeinate(ctx, "manual stop", generation);
 			return;
 	}
 
@@ -215,7 +248,7 @@ async function runCaffeinateMenu(ctx: CommandContext, generation: number, start:
 				return { kind: "close" };
 			},
 			stop: async () => {
-				stopCaffeinate(ctx, "manual stop");
+				await stopCaffeinate(ctx, "manual stop", generation);
 				return { kind: "close" };
 			},
 			help: async () => {
@@ -264,18 +297,23 @@ async function setModeNow(ctx: ExtensionContext, mode: CaffeinateMode, generatio
 	if (generation !== state.sessionGeneration) return;
 	const previousMode = state.mode;
 	const previousQuiet = state.quiet;
-	const restartRequired = Boolean(state.process && previousMode !== mode && !state.command?.custom);
+	const restartRequired = Boolean(
+		hasActiveInhibitor() && previousMode !== mode && !state.command?.custom,
+	);
 	state.settingsError = undefined;
 
 	if (restartRequired) {
 		state.mode = mode;
-		stopInhibitor(ctx, "mode changed", { notify: false });
-		startInhibitor(ctx, { notify: false });
-		if (!state.process) {
+		await stopInhibitor(ctx, "mode changed", { notify: false });
+		if (generation !== state.sessionGeneration) return;
+		await startInhibitor(ctx, generation, { notify: false });
+		if (generation !== state.sessionGeneration) return;
+		if (!hasActiveInhibitor()) {
 			const applicationError = state.lastError ?? "the inhibitor could not be restarted";
 			state.mode = previousMode;
-			startInhibitor(ctx, { notify: false });
-			const rollbackError = state.process
+			await startInhibitor(ctx, generation, { notify: false });
+			if (generation !== state.sessionGeneration) return;
+			const rollbackError = hasActiveInhibitor()
 				? undefined
 				: (state.lastError ?? "the previous inhibitor could not be restored");
 			state.settingsError = rollbackError
@@ -296,9 +334,13 @@ async function setModeNow(ctx: ExtensionContext, mode: CaffeinateMode, generatio
 		if (restartRequired) {
 			state.mode = previousMode;
 			state.quiet = previousQuiet;
-			stopInhibitor(ctx, "settings save failed", { notify: false });
-			startInhibitor(ctx, { notify: false });
-			if (!state.process) rollbackError = state.lastError ?? "the prior inhibitor was not restored";
+			await stopInhibitor(ctx, "settings save failed", { notify: false });
+			if (generation !== state.sessionGeneration) return;
+			await startInhibitor(ctx, generation, { notify: false });
+			if (generation !== state.sessionGeneration) return;
+			if (!hasActiveInhibitor()) {
+				rollbackError = state.lastError ?? "the prior inhibitor was not restored";
+			}
 		}
 		state.settingsError = rollbackError
 			? `settings save failed (${formatError(error)}); runtime rollback failed: ${rollbackError}`
@@ -323,9 +365,10 @@ function showStatus(ctx: ExtensionContext) {
 	updateStatus(ctx);
 }
 
-function stopCaffeinate(ctx: ExtensionContext, reason: string) {
+async function stopCaffeinate(ctx: ExtensionContext, reason: string, sessionGeneration: number) {
 	state.activeTurns = 0;
-	stopInhibitor(ctx, reason);
+	await stopInhibitor(ctx, reason);
+	if (sessionGeneration !== state.sessionGeneration) return;
 	updateStatus(ctx);
 }
 
@@ -363,14 +406,24 @@ function buildCommandGuide() {
 	].join("\n");
 }
 
-function startInhibitor(ctx: ExtensionContext, options: { notify?: boolean } = {}) {
-	if (state.disabled || state.process) {
+async function startInhibitor(
+	ctx: ExtensionContext,
+	sessionGeneration: number,
+	options: { notify?: boolean } = {},
+) {
+	if (state.disabled || hasActiveInhibitor() || state.inhibitorStarting) {
 		updateStatus(ctx);
 		return;
 	}
 
+	const token = ++inhibitSequence;
 	const command = getInhibitorCommand(state.mode);
-	if (!command) {
+	const wantsDbus =
+		!command?.custom &&
+		state.mode === "display" &&
+		process.platform === "linux" &&
+		(command === undefined || command.addDbusIdleInhibit === true);
+	if (!command && !wantsDbus) {
 		state.available = false;
 		state.lastError = `No supported sleep inhibitor found for ${process.platform}.`;
 		ctx.ui.notify(state.lastError, "warning");
@@ -378,56 +431,242 @@ function startInhibitor(ctx: ExtensionContext, options: { notify?: boolean } = {
 		return;
 	}
 
-	try {
-		const child = startInhibitorProcess(
-			command,
-			(error) => {
-				if (state.process === child) {
-					state.process = undefined;
-					state.startedAt = undefined;
-				}
-				state.available = false;
-				state.lastError = `${command.description} failed: ${error.message}`;
-				ctx.ui.notify(state.lastError, "warning");
-				updateStatus(ctx);
-			},
-			(exit) => {
-				if (state.process !== child) return;
-				state.process = undefined;
-				state.startedAt = undefined;
-				state.available = false;
-				state.lastError = `${command.description} exited unexpectedly (${exit}).`;
-				ctx.ui.notify(state.lastError, "warning");
-				updateStatus(ctx);
-			},
-		);
-		state.process = child;
-		state.startedAt = Date.now();
-		state.command = command;
-		state.available = true;
-		state.lastError = undefined;
-		if (options.notify !== false) {
-			ctx.ui.notify(`Keeping computer awake (${statusModeLabel()}).`, "info");
-		}
-		updateStatus(ctx);
-	} catch (error) {
+	state.inhibitorStarting = true;
+	state.inhibitWarning = undefined;
+	let child: ChildProcess | undefined;
+	let childError =
+		!command && wantsDbus
+			? "No supported system sleep inhibitor is available; direct system suspend may remain possible."
+			: undefined;
+	let assembling = true;
+	const handleChildFailure = (message: string) => {
+		if (!child || token !== inhibitSequence || state.process !== child) return;
 		state.process = undefined;
+		state.command = undefined;
+		if (assembling) {
+			childError = message;
+			return;
+		}
+		applyChildFailure(message);
+	};
+
+	if (command) {
+		try {
+			child = startInhibitorProcess(
+				command,
+				(error) => handleChildFailure(`${command.description} failed: ${error.message}`),
+				(exit) => handleChildFailure(`${command.description} exited unexpectedly (${exit}).`),
+			);
+			state.process = child;
+			state.command = command;
+			state.startedAt = Date.now();
+		} catch (error) {
+			childError = `${command.description}: ${formatError(error)}`;
+		}
+	}
+
+	let dbus: DbusScreenSaverClient | undefined;
+	let dbusError: string | undefined;
+	if (wantsDbus) {
+		const pending: PendingDbusStart = { token, controller: new AbortController() };
+		state.pendingDbus = pending;
+		try {
+			const client = await dbusFactory();
+			if (!pendingStartIsCurrent(pending, sessionGeneration)) {
+				await client.close().catch(() => undefined);
+				await cancelPendingStart(token, child, command);
+				return;
+			}
+			pending.client = client;
+			await client.inhibit(INHIBIT_REASON, pending.controller.signal);
+			if (!pendingStartIsCurrent(pending, sessionGeneration)) {
+				await cancelPendingStart(token, child, command);
+				return;
+			}
+			pending.client = undefined;
+			state.pendingDbus = undefined;
+			dbus = client;
+		} catch (error) {
+			const stale =
+				!pendingStartIsCurrent(pending, sessionGeneration) || pending.controller.signal.aborted;
+			const pendingClient = takePendingDbusClient(pending);
+			await pendingClient?.close().catch(() => undefined);
+			if (stale) {
+				await cancelPendingStart(token, child, command);
+				return;
+			}
+			dbusError = `D-Bus idle inhibit (${SCREENSAVER_BUS_NAME}): ${formatError(error)}`;
+		}
+	}
+
+	assembling = false;
+	if (startIsStale(token, sessionGeneration)) {
+		await cancelPendingStart(token, child, command);
+		await dbus?.close().catch(() => undefined);
+		return;
+	}
+
+	state.inhibitorStarting = false;
+	state.dbus = dbus;
+	if (dbus) {
+		dbus.setFailureHandler((error) => applyDbusFailure(token, dbus, error));
+		if (state.dbus !== dbus) return;
+	}
+	const failures = [childError, dbusError].filter((failure): failure is string => Boolean(failure));
+	if (!hasActiveInhibitor()) {
 		state.startedAt = undefined;
+		state.command = undefined;
 		state.available = false;
-		state.lastError = error instanceof Error ? error.message : String(error);
-		ctx.ui.notify(`Unable to start pi-caffeinate: ${state.lastError}`, "warning");
+		state.lastError =
+			failures.join("; ") || `No supported sleep inhibitor found for ${process.platform}.`;
+		ctx.ui.notify(state.lastError, "warning");
 		updateStatus(ctx);
+		return;
+	}
+
+	state.startedAt ??= Date.now();
+	state.available = true;
+	state.lastError = undefined;
+	state.inhibitWarning = failures.length > 0 ? failures.join("; ") : undefined;
+	if (state.inhibitWarning) {
+		ctx.ui.notify(`pi-caffeinate is partially active: ${state.inhibitWarning}`, "warning");
+	} else if (options.notify !== false) {
+		ctx.ui.notify(`Keeping computer awake (${statusModeLabel()}).`, "info");
 	}
+	updateStatus(ctx);
 }
 
-function stopInhibitor(ctx: ExtensionContext, reason: string, options: { notify?: boolean } = {}) {
+async function stopInhibitor(
+	ctx: ExtensionContext,
+	reason: string,
+	options: { notify?: boolean } = {},
+) {
+	inhibitSequence += 1;
 	const child = state.process;
-	if (!child) return;
+	const dbus = state.dbus;
+	const dbusCleanup = state.dbusCleanup;
+	const pending = state.pendingDbus;
+	const command = state.command;
+	const wasStarting = state.inhibitorStarting;
 	state.process = undefined;
-	state.startedAt = undefined;
-	stopInhibitorProcess(child, state.command);
+	state.dbus = undefined;
+	state.dbusCleanup = undefined;
+	state.pendingDbus = undefined;
 	state.command = undefined;
+	state.startedAt = undefined;
+	state.inhibitWarning = undefined;
+	state.inhibitorStarting = false;
+	dbus?.setFailureHandler(undefined);
+	pending?.controller.abort(new DOMException(`Caffeinate stopped: ${reason}`, "AbortError"));
+	const pendingClient = pending ? takePendingDbusClient(pending) : undefined;
+	if (child) stopInhibitorProcess(child, command);
+	if (!child && !dbus && !pendingClient && !wasStarting) {
+		await dbusCleanup;
+		return;
+	}
 	if (options.notify !== false) ctx.ui.notify(`Released pi-caffeinate (${reason}).`, "info");
+	await Promise.all([dbusCleanup, pendingClient?.close().catch(() => undefined)]);
+	if (!dbus) return;
+	try {
+		await dbus.uninhibit();
+	} catch {
+		// Closing the session-bus connection also releases its inhibition cookie.
+	}
+	await dbus.close().catch(() => undefined);
+}
+
+function applyChildFailure(message: string) {
+	if (state.dbus) {
+		state.available = true;
+		state.lastError = undefined;
+		state.inhibitWarning = message;
+	} else {
+		state.startedAt = undefined;
+		state.available = false;
+		state.lastError = message;
+		state.inhibitWarning = undefined;
+	}
+	const ctx = currentSessionContext();
+	if (!ctx) return;
+	ctx.ui.notify(message, "warning");
+	updateStatus(ctx);
+}
+
+function applyDbusFailure(token: number, client: DbusScreenSaverClient, error: Error) {
+	if (token !== inhibitSequence || state.dbus !== client) return;
+	client.setFailureHandler(undefined);
+	state.dbus = undefined;
+	const message = `D-Bus idle inhibit (${SCREENSAVER_BUS_NAME}) failed: ${formatError(error)}`;
+	const notification = state.process ? `pi-caffeinate is partially active: ${message}` : message;
+	if (state.process) {
+		state.available = true;
+		state.lastError = undefined;
+		state.inhibitWarning = message;
+	} else {
+		state.startedAt = undefined;
+		state.command = undefined;
+		state.available = false;
+		state.lastError = [state.inhibitWarning, message].filter(Boolean).join("; ");
+		state.inhibitWarning = undefined;
+	}
+	const cleanup = client.close().catch(() => undefined);
+	state.dbusCleanup = cleanup;
+	void cleanup.then(() => {
+		if (state.dbusCleanup === cleanup) state.dbusCleanup = undefined;
+	});
+	const ctx = currentSessionContext();
+	if (!ctx) return;
+	ctx.ui.notify(notification, "warning");
+	updateStatus(ctx);
+}
+
+function currentSessionContext() {
+	const session = state.currentSession;
+	return session?.generation === state.sessionGeneration ? session.ctx : undefined;
+}
+
+function hasActiveInhibitor() {
+	return Boolean(state.process || state.dbus);
+}
+
+function startIsStale(token: number, sessionGeneration: number) {
+	return token !== inhibitSequence || sessionGeneration !== state.sessionGeneration;
+}
+
+function pendingStartIsCurrent(pending: PendingDbusStart, sessionGeneration: number) {
+	return (
+		state.pendingDbus === pending &&
+		!pending.controller.signal.aborted &&
+		!startIsStale(pending.token, sessionGeneration)
+	);
+}
+
+function takePendingDbusClient(pending: PendingDbusStart) {
+	if (state.pendingDbus === pending) state.pendingDbus = undefined;
+	const client = pending.client;
+	pending.client = undefined;
+	return client;
+}
+
+async function cancelPendingStart(
+	token: number,
+	child: ChildProcess | undefined,
+	command: InhibitorCommand | undefined,
+) {
+	if (token !== inhibitSequence) return;
+	inhibitSequence += 1;
+	state.inhibitorStarting = false;
+	const pending = state.pendingDbus?.token === token ? state.pendingDbus : undefined;
+	state.pendingDbus = undefined;
+	pending?.controller.abort(new DOMException("Caffeinate start cancelled", "AbortError"));
+	const pendingClient = pending ? takePendingDbusClient(pending) : undefined;
+	if (child && state.process === child) {
+		state.process = undefined;
+		state.command = undefined;
+		state.startedAt = undefined;
+		stopInhibitorProcess(child, command);
+	}
+	await pendingClient?.close().catch(() => undefined);
 }
 
 function updateStatus(ctx: ExtensionContext) {
@@ -436,7 +675,7 @@ function updateStatus(ctx: ExtensionContext) {
 		return;
 	}
 
-	if (state.process) {
+	if (hasActiveInhibitor()) {
 		ctx.ui.setStatus(STATUS_KEY, withDeprecatedIcon(statusModeLabel()));
 		return;
 	}
@@ -465,11 +704,15 @@ function describeState() {
 		return lines.join("\n");
 	}
 
-	if (state.process) {
+	if (hasActiveInhibitor()) {
 		const seconds = state.startedAt ? Math.round((Date.now() - state.startedAt) / 1000) : 0;
+		const activeParts: string[] = [];
+		if (state.dbus) activeParts.push(`D-Bus idle inhibit (${SCREENSAVER_BUS_NAME})`);
+		if (state.process && state.command) activeParts.push(state.command.description);
 		lines.unshift(
-			`pi-caffeinate is active using ${state.command?.description ?? "an inhibitor"} for ${seconds}s.`,
+			`pi-caffeinate is active using ${activeParts.join(" + ") || "an inhibitor"} for ${seconds}s.`,
 		);
+		if (state.inhibitWarning) lines.push(`Inhibitor warning: ${state.inhibitWarning}`);
 		return lines.join("\n");
 	}
 
@@ -485,7 +728,7 @@ function describeState() {
 }
 
 function statusLevel() {
-	return state.available && !state.settingsError ? "info" : "warning";
+	return state.available && !state.settingsError && !state.inhibitWarning ? "info" : "warning";
 }
 
 function statusModeLabel() {
@@ -559,5 +802,10 @@ function warnDeprecatedIcon(ctx: ExtensionContext) {
 	);
 }
 
-export { formatMode, splitCommand, windowsInhibitorScript } from "./inhibitors.js";
+export {
+	formatMode,
+	getInhibitorCommand,
+	splitCommand,
+	windowsInhibitorScript,
+} from "./inhibitors.js";
 export { normalizeCaffeinateSettings } from "./settings.js";

package/src/dbus-inhibit.ts

@@ -0,0 +1,152 @@
+import { type Message, type MessageBus, sessionBus } from "dbus-native";
+
+export const SCREENSAVER_BUS_NAME = "org.freedesktop.ScreenSaver";
+export const SCREENSAVER_INTERFACE = "org.freedesktop.ScreenSaver";
+export const INHIBIT_REASON = "Pi agent is running";
+
+const INHIBIT_APPLICATION_NAME = "pi-caffeinate";
+const SCREENSAVER_OBJECT_PATHS = ["/org/freedesktop/ScreenSaver", "/ScreenSaver"];
+const DBUS_CALL_TIMEOUT_MS = 2_000;
+
+type DbusFailureHandler = (error: Error) => void;
+
+export interface DbusScreenSaverClient {
+	setFailureHandler(handler: DbusFailureHandler | undefined): void;
+	inhibit(reason: string, signal?: AbortSignal): Promise<void>;
+	uninhibit(): Promise<void>;
+	close(): Promise<void>;
+}
+
+export type DbusScreenSaverFactory = () => Promise<DbusScreenSaverClient>;
+
+export async function defaultDbusScreenSaverFactory(): Promise<DbusScreenSaverClient> {
+	return new NativeScreenSaverClient(sessionBus());
+}
+
+class NativeScreenSaverClient implements DbusScreenSaverClient {
+	private cookie?: number;
+	private objectPath?: string;
+	private failureHandler?: DbusFailureHandler;
+	private pendingFailure?: Error;
+	private lastConnectionError?: Error;
+	private closing = false;
+
+	private readonly handleConnectionError = (error: unknown) => {
+		this.lastConnectionError = toError(error, "D-Bus session connection failed");
+		if (this.cookie !== undefined) this.reportFailure(this.lastConnectionError);
+	};
+
+	private readonly handleConnectionClose = (error?: unknown) => {
+		if (this.closing || this.cookie === undefined) return;
+		this.reportFailure(
+			toError(error, this.lastConnectionError?.message ?? "D-Bus session connection closed"),
+		);
+	};
+
+	constructor(private readonly bus: MessageBus) {
+		this.bus.connection.on("error", this.handleConnectionError);
+		this.bus.connection.on("close", this.handleConnectionClose);
+	}
+
+	setFailureHandler(handler: DbusFailureHandler | undefined): void {
+		this.failureHandler = handler;
+		if (!handler || !this.pendingFailure) return;
+		const failure = this.pendingFailure;
+		this.pendingFailure = undefined;
+		handler(failure);
+	}
+
+	async inhibit(reason: string, signal?: AbortSignal): Promise<void> {
+		let lastError: unknown;
+		for (const objectPath of SCREENSAVER_OBJECT_PATHS) {
+			if (signal?.aborted) throw abortReason(signal);
+			try {
+				this.cookie = await invoke<number>(
+					this.bus,
+					{
+						destination: SCREENSAVER_BUS_NAME,
+						path: objectPath,
+						interface: SCREENSAVER_INTERFACE,
+						member: "Inhibit",
+						signature: "ss",
+						body: [INHIBIT_APPLICATION_NAME, reason],
+					},
+					signal,
+				);
+				this.objectPath = objectPath;
+				return;
+			} catch (error) {
+				if (signal?.aborted) throw abortReason(signal);
+				lastError = error;
+			}
+		}
+		throw new Error(`D-Bus idle inhibit failed: ${formatError(lastError)}`, {
+			cause: lastError,
+		});
+	}
+
+	async uninhibit(): Promise<void> {
+		if (this.cookie === undefined || !this.objectPath) return;
+		const cookie = this.cookie;
+		this.cookie = undefined;
+		const objectPath = this.objectPath;
+		this.objectPath = undefined;
+		await invoke<void>(this.bus, {
+			destination: SCREENSAVER_BUS_NAME,
+			path: objectPath,
+			interface: SCREENSAVER_INTERFACE,
+			member: "UnInhibit",
+			signature: "u",
+			body: [cookie],
+		});
+	}
+
+	async close(): Promise<void> {
+		this.closing = true;
+		this.cookie = undefined;
+		this.objectPath = undefined;
+		this.failureHandler = undefined;
+		try {
+			await this.bus.close();
+		} finally {
+			this.bus.connection.off("error", this.handleConnectionError);
+			this.bus.connection.off("close", this.handleConnectionClose);
+		}
+	}
+
+	private reportFailure(error: Error): void {
+		if (this.cookie === undefined) return;
+		this.cookie = undefined;
+		this.objectPath = undefined;
+		if (this.failureHandler) this.failureHandler(error);
+		else this.pendingFailure = error;
+	}
+}
+
+function invoke<TResult>(
+	bus: MessageBus,
+	message: Message,
+	signal?: AbortSignal,
+): Promise<TResult> {
+	return new Promise<TResult>((resolve, reject) => {
+		bus.invoke(message, { signal, timeout: DBUS_CALL_TIMEOUT_MS }, (error, ...values) => {
+			if (error) reject(error);
+			else resolve(values[0] as TResult);
+		});
+	});
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("D-Bus idle inhibit cancelled", "AbortError");
+}
+
+function toError(error: unknown, fallback: string): Error {
+	return error instanceof Error ? error : new Error(fallback);
+}
+
+function formatError(error: unknown) {
+	if (error instanceof Error) {
+		return error.name === "Error" ? error.message : `${error.name}: ${error.message}`;
+	}
+	return String(error);
+}