@narumitw/pi-caffeinate 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 narumiruna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# pi-caffeinate
+
+A public [pi](https://pi.dev) extension package that keeps your computer awake while the pi agent is processing a prompt.
+
+The extension starts an OS sleep inhibitor on `agent_start` and releases it on `agent_end` or `session_shutdown`.
+
+## Install
+
+```bash
+pi install npm:@narumitw/pi-caffeinate
+```
+
+Try without installing:
+
+```bash
+pi -e npm:@narumitw/pi-caffeinate
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-caffeinate
+```
+
+## Supported platforms
+
+- macOS: uses `caffeinate -dimsu`
+- Windows: uses PowerShell `SetThreadExecutionState`
+- WSL: uses Windows `powershell.exe` with `SetThreadExecutionState`
+- Linux: uses `systemd-inhibit` with `sleep infinity`
+- Linux fallback: uses `caffeinate -dimsu` if available
+
+If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.
+
+## Commands
+
+```text
+/caffeinate-status
+```
+
+Shows whether an inhibitor is active, unavailable, or disabled.
+
+```text
+/caffeinate-stop
+```
+
+Manually releases any active inhibitor for the current session.
+
+## Configuration
+
+Disable the extension:
+
+```bash
+PI_CAFFEINATE_DISABLED=1 pi
+```
+
+Use a custom inhibitor command:
+
+```bash
+PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' pi
+```
+
+The custom command is parsed with shell-like quoting and is run directly without a shell.
+
+## Package layout
+
+```txt
+extensions/pi-caffeinate/
+├── src/
+│   └── caffeinate.ts
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@narumitw/pi-caffeinate",
+	"version": "0.1.3",
+	"description": "Pi extension that keeps the computer awake while the agent is running.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"caffeinate",
+		"awake",
+		"sleep"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/caffeinate.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@mariozechner/pi-coding-agent": "0.73.0",
+		"@types/node": "25.6.0",
+		"typescript": "6.0.3"
+	}
+}

package/src/caffeinate.ts

@@ -0,0 +1,318 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import pathModule from "node:path";
+import process from "node:process";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+const STATUS_KEY = "caffeinate";
+const DISABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+
+interface InhibitorCommand {
+	command: string;
+	args: string[];
+	description: string;
+}
+
+interface CaffeinateState {
+	process?: ChildProcess;
+	startedAt?: number;
+	command?: InhibitorCommand;
+	lastError?: string;
+	activeTurns: number;
+	available: boolean;
+	disabled: boolean;
+}
+
+const state: CaffeinateState = {
+	activeTurns: 0,
+	available: true,
+	disabled: isDisabled(),
+};
+
+export default function caffeinate(pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		updateStatus(ctx);
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		state.activeTurns += 1;
+		startInhibitor(ctx);
+	});
+
+	pi.on("agent_end", (_event, ctx) => {
+		state.activeTurns = Math.max(0, state.activeTurns - 1);
+		if (state.activeTurns === 0) stopInhibitor(ctx, "agent finished");
+		updateStatus(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		state.activeTurns = 0;
+		stopInhibitor(ctx, "session shutdown", { notify: false });
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+	});
+
+	pi.registerCommand("caffeinate-status", {
+		description: "Show whether pi-caffeinate is currently keeping the computer awake",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify(describeState(), state.process ? "info" : state.available ? "info" : "warning");
+			updateStatus(ctx);
+		},
+	});
+
+	pi.registerCommand("caffeinate-stop", {
+		description: "Release the active pi-caffeinate sleep inhibitor",
+		handler: async (_args, ctx) => {
+			state.activeTurns = 0;
+			stopInhibitor(ctx, "manual stop");
+			updateStatus(ctx);
+		},
+	});
+}
+
+function startInhibitor(ctx: ExtensionContext) {
+	if (state.disabled) {
+		updateStatus(ctx);
+		return;
+	}
+
+	if (state.process) {
+		updateStatus(ctx);
+		return;
+	}
+
+	const command = getInhibitorCommand();
+	if (!command) {
+		state.available = false;
+		state.lastError = `No supported sleep inhibitor found for ${process.platform}.`;
+		ctx.ui.notify(state.lastError, "warning");
+		updateStatus(ctx);
+		return;
+	}
+
+	try {
+		const child = spawn(command.command, command.args, {
+			detached: false,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		state.process = child;
+		state.startedAt = Date.now();
+		state.command = command;
+		state.available = true;
+		state.lastError = undefined;
+
+		child.once("error", (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);
+		});
+
+		child.once("exit", (code, signal) => {
+			if (state.process !== child) return;
+			state.process = undefined;
+			state.startedAt = undefined;
+			state.lastError = `${command.description} exited unexpectedly (${formatExit(code, signal)}).`;
+			ctx.ui.notify(state.lastError, "warning");
+			updateStatus(ctx);
+		});
+
+		ctx.ui.notify(`Keeping computer awake with ${command.description}.`, "info");
+		updateStatus(ctx);
+	} catch (error) {
+		state.process = undefined;
+		state.startedAt = undefined;
+		state.available = false;
+		state.lastError = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Unable to start pi-caffeinate: ${state.lastError}`, "warning");
+		updateStatus(ctx);
+	}
+}
+
+function stopInhibitor(ctx: ExtensionContext, reason: string, options: { notify?: boolean } = {}) {
+	const child = state.process;
+	if (!child) return;
+
+	state.process = undefined;
+	state.startedAt = undefined;
+
+	child.removeAllListeners("exit");
+	child.removeAllListeners("error");
+
+	if (!child.killed) {
+		if (process.platform === "win32") {
+			child.kill();
+		} else {
+			child.kill("SIGTERM");
+		}
+	}
+
+	if (options.notify !== false) {
+		ctx.ui.notify(`Released pi-caffeinate (${reason}).`, "info");
+	}
+}
+
+function getInhibitorCommand(): InhibitorCommand | undefined {
+	const customCommand = process.env.PI_CAFFEINATE_COMMAND?.trim();
+	if (customCommand) {
+		const [command, ...args] = splitCommand(customCommand);
+		if (command) return { command, args, description: command };
+	}
+
+	if (process.platform === "darwin") {
+		return { command: "caffeinate", args: ["-dimsu"], description: "caffeinate" };
+	}
+
+	if (process.platform === "linux") {
+		if (isWsl() && commandExists("powershell.exe")) {
+			return windowsPowerInhibitorCommand("powershell.exe");
+		}
+
+		if (commandExists("systemd-inhibit")) {
+			return {
+				command: "systemd-inhibit",
+				args: [
+					"--what=idle:sleep",
+					"--who=pi-caffeinate",
+					"--why=Pi agent is running",
+					"--mode=block",
+					"sleep",
+					"infinity",
+				],
+				description: "systemd-inhibit",
+			};
+		}
+
+		if (commandExists("caffeinate")) {
+			return { command: "caffeinate", args: ["-dimsu"], description: "caffeinate" };
+		}
+	}
+
+	if (process.platform === "win32") {
+		return windowsPowerInhibitorCommand("powershell.exe");
+	}
+
+	return undefined;
+}
+
+function commandExists(command: string) {
+	const path = process.env.PATH ?? "";
+	const extensions = process.platform === "win32" ? ["", ".exe", ".cmd", ".bat"] : [""];
+
+	for (const directory of path.split(process.platform === "win32" ? ";" : ":")) {
+		if (!directory) continue;
+		for (const extension of extensions) {
+			const candidate = pathModule.join(directory, `${command}${extension}`);
+			if (existsSync(candidate)) return true;
+		}
+	}
+
+	return false;
+}
+
+function splitCommand(input: string) {
+	const parts: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | undefined;
+	let escaping = false;
+
+	for (const char of input) {
+		if (escaping) {
+			current += char;
+			escaping = false;
+			continue;
+		}
+
+		if (char === "\\") {
+			escaping = true;
+			continue;
+		}
+
+		if ((char === '"' || char === "'") && !quote) {
+			quote = char;
+			continue;
+		}
+
+		if (char === quote) {
+			quote = undefined;
+			continue;
+		}
+
+		if (/\s/.test(char) && !quote) {
+			if (current) {
+				parts.push(current);
+				current = "";
+			}
+			continue;
+		}
+
+		current += char;
+	}
+
+	if (current) parts.push(current);
+	return parts;
+}
+
+function windowsPowerInhibitorCommand(command: string): InhibitorCommand {
+	return {
+		command,
+		args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", windowsInhibitorScript()],
+		description: "PowerShell SetThreadExecutionState",
+	};
+}
+
+function windowsInhibitorScript() {
+	return `Add-Type -Namespace Native -Name Power -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint esFlags);'; while ($true) { [Native.Power]::SetThreadExecutionState(0x80000000 -bor 0x00000001 -bor 0x00000002) | Out-Null; Start-Sleep -Seconds 30 }`;
+}
+
+function isWsl() {
+	try {
+		return existsSync("/proc/sys/fs/binfmt_misc/WSLInterop");
+	} catch {
+		return false;
+	}
+}
+
+function updateStatus(ctx: ExtensionContext) {
+	if (state.disabled) {
+		ctx.ui.setStatus(STATUS_KEY, "caffeinate: disabled");
+		return;
+	}
+
+	if (state.process) {
+		ctx.ui.setStatus(STATUS_KEY, `caffeinate: on (${state.command?.description ?? "active"})`);
+		return;
+	}
+
+	if (!state.available) {
+		ctx.ui.setStatus(STATUS_KEY, "caffeinate: unavailable");
+		return;
+	}
+
+	ctx.ui.setStatus(STATUS_KEY, "caffeinate: idle");
+}
+
+function describeState() {
+	if (state.disabled) return "pi-caffeinate is disabled by PI_CAFFEINATE_DISABLED.";
+	if (state.process) {
+		const seconds = state.startedAt ? Math.round((Date.now() - state.startedAt) / 1000) : 0;
+		return `pi-caffeinate is active using ${state.command?.description ?? "an inhibitor"} for ${seconds}s.`;
+	}
+	if (!state.available)
+		return `pi-caffeinate is unavailable: ${state.lastError ?? "unknown reason"}`;
+	return "pi-caffeinate is idle and will keep the computer awake during the next agent run.";
+}
+
+function formatExit(code: number | null, signal: NodeJS.Signals | null) {
+	if (signal) return `signal ${signal}`;
+	return `code ${code ?? "unknown"}`;
+}
+
+function isDisabled() {
+	const value = process.env.PI_CAFFEINATE_DISABLED?.trim().toLowerCase();
+	return value ? DISABLED_VALUES.has(value) : false;
+}