pi-insomnia 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows the spirit of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning for releases.
+
+## [Unreleased]
+
+## [0.1.0] - TBD
+
+### Added
+
+- Initial `pi-insomnia` package scaffold.
+- Automatic macOS idle sleep inhibition while Pi agent runs are active.
+- Cleanup on agent completion and session shutdown.
+- Footer status indicator while sleep inhibition is active.
+- Best-effort install/update telemetry ping to `mocito.dev`, gated by Pi telemetry/offline settings and disabled in CI.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior and may remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct.
+
+## Scope
+
+This Code of Conduct applies within all project spaces and also applies when an individual is officially representing the project in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers through GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-insomnia`.
+
+## Development setup
+
+```bash
+npm install
+npm run check
+```
+
+This package is source-distributed: Pi loads the TypeScript extension files directly. There is no build step for runtime use.
+
+## Local testing
+
+Install this checkout into a temporary Pi project:
+
+```bash
+mkdir -p <test-project>
+cd <test-project>
+pi install -l /path/to/pi-mono/packages/pi-insomnia
+pi
+```
+
+For a one-off run without changing settings:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-insomnia --print "list loaded extensions"
+```
+
+## Pull request checklist
+
+Before opening a pull request:
+
+- Run `npm run check`.
+- Run `npm audit --omit=dev`.
+- Run `npm run pack:dry-run` and confirm the package contents are intentional.
+- Update `README.md` if user-facing behavior changes.
+- Update `CHANGELOG.md` for notable changes.
+- Keep examples and paths generic; do not commit machine-specific paths, API keys, tokens, or provider config containing secrets.
+
+## Coding guidelines
+
+- Keep `extensions/index.ts` focused on Pi extension wiring and move reusable implementation details into `src/`.
+- Avoid adding commands or tools unless they are necessary; the default package behavior should remain automatic when installed.
+- Treat config keys and environment variables as public interface; changes to defaults or precedence are breaking changes.
+- Keep macOS-specific power-management behavior isolated so future platform backends can be added without changing extension wiring.
+
+## Code of conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Mocito
+
+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,78 @@
+# pi-insomnia
+
+A source-distributed [Pi](https://pi.dev) package that prevents macOS idle sleep while the Pi agent is working.
+
+> [!WARNING]
+> Pi packages can execute arbitrary code through extensions. Review package source before installing any third-party Pi package.
+
+## Features
+
+- Automatically starts a macOS sleep assertion when a Pi agent run starts.
+- Automatically releases the assertion when the agent run ends.
+- Cleans up on Pi session shutdown, reloads, and quits.
+- Uses the macOS built-in `/usr/bin/caffeinate` command; no third-party runtime dependency is required.
+- Shows a small `☕ sleep inhibited` footer status while active in UI modes.
+- No slash commands, tools, or manual activation needed.
+
+## Platform support
+
+`pi-insomnia` currently targets macOS. On non-macOS platforms it silently no-ops.
+
+On macOS, the extension launches:
+
+```bash
+/usr/bin/caffeinate -i -w <pi-pid>
+```
+
+`-i` prevents idle system sleep while the process is running. `-w <pi-pid>` also ties the assertion to the Pi process so the helper exits if Pi exits unexpectedly. The extension still explicitly terminates the helper when the agent becomes idle.
+
+## Installation
+
+Install from npm:
+
+```bash
+pi install npm:pi-insomnia
+```
+
+Install project-locally with Pi's `-l` flag:
+
+```bash
+pi install -l npm:pi-insomnia
+```
+
+During local development from this monorepo:
+
+```bash
+pi install /path/to/pi-mono/packages/pi-insomnia
+```
+
+For a one-off test run without installing:
+
+```bash
+pi -e /path/to/pi-mono/packages/pi-insomnia --print "explain what this package does"
+```
+
+This is an npm-compatible TypeScript Pi package. There is no runtime build step.
+
+## Configuration
+
+| Variable | Purpose |
+|---|---|
+| `PI_OFFLINE=1` | Disables install/update telemetry. |
+| `PI_TELEMETRY=0` | Disables install/update telemetry. |
+
+`pi-insomnia` has no behavior configuration. If the package is installed and Pi is running on macOS, sleep inhibition is automatic while the agent is working.
+
+## Notes
+
+- The extension inhibits idle system sleep, not display sleep. It does not use `caffeinate -d`.
+- The extension does not request elevated privileges.
+- On startup, Pi Insomnia sends a best-effort install/update telemetry ping once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm run pack:dry-run
+```

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest released version of `pi-insomnia`.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for suspected security vulnerabilities.
+
+Report privately by contacting the repository maintainer through GitHub. Include:
+
+- a description of the issue;
+- steps to reproduce;
+- affected versions or commits, if known;
+- any suggested mitigation.
+
+The maintainer will acknowledge reports as soon as practical and coordinate disclosure once a fix or mitigation is available.
+
+## Security model
+
+`pi-insomnia` is a Pi package. Pi extensions execute with the same permissions as the local user running Pi. Users should review installed Pi packages and only install packages from sources they trust.
+
+Do not commit API keys, tokens, credentials, local settings, or machine-specific paths.
+
+On macOS, the extension starts the system-provided `/usr/bin/caffeinate` helper while the Pi agent is working. It does not request elevated privileges, pass user prompts to the helper, or run shell commands. The helper is started directly with fixed arguments and is terminated when the agent becomes idle or the Pi session shuts down.
+
+On startup, the extension sends a best-effort install/update telemetry ping to `mocito.dev` once per package version unless Pi telemetry is disabled, offline mode is enabled, or Pi runs in CI. The ping includes only the package name, version, and parsed platform/runtime/architecture from its User-Agent; it does not include prompts, file paths, config values, environment variables, or API keys.

package/extensions/index.ts

@@ -0,0 +1,30 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { reportInstallTelemetry } from "../src/install-telemetry.js";
+import { MacSleepInhibitor } from "../src/sleep-inhibitor.js";
+
+const STATUS_KEY = "pi-insomnia";
+
+function setStatus(ctx: ExtensionContext, active: boolean): void {
+  if (!ctx.hasUI) return;
+  ctx.ui.setStatus(STATUS_KEY, active ? "☕ sleep inhibited" : undefined);
+}
+
+export default function piInsomnia(pi: ExtensionAPI) {
+  reportInstallTelemetry();
+
+  const inhibitor = new MacSleepInhibitor();
+
+  pi.on("agent_start", async (_event, ctx) => {
+    if (inhibitor.acquire()) setStatus(ctx, true);
+  });
+
+  pi.on("agent_end", async (_event, ctx) => {
+    inhibitor.release();
+    if (!inhibitor.isInhibiting) setStatus(ctx, false);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    inhibitor.forceStop();
+    setStatus(ctx, false);
+  });
+}

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./extensions/index.js";

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-insomnia",
+  "version": "0.1.0",
+  "description": "Prevent macOS idle sleep while Pi agents are working.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jose Mocito",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jvm/pi-mono.git",
+    "directory": "packages/pi-insomnia"
+  },
+  "bugs": {
+    "url": "https://github.com/jvm/pi-mono/issues"
+  },
+  "homepage": "https://github.com/jvm/pi-mono/tree/main/packages/pi-insomnia#readme",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "macos",
+    "sleep",
+    "caffeinate",
+    "insomnia"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@types/node": "^25.6.2",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export const PACKAGE_NAME = "pi-insomnia";
+
+export * from "./sleep-inhibitor.js";

package/src/install-telemetry.ts

@@ -0,0 +1,104 @@
+import { readFileSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const PACKAGE_NAME = "pi-insomnia";
+const INSTALL_TELEMETRY_URL = "https://mocito.dev/api/report-install";
+const INSTALL_TELEMETRY_TIMEOUT_MS = 5000;
+const CI_ENVIRONMENT_VARIABLES = [
+  "APPVEYOR",
+  "BITBUCKET_BUILD_NUMBER",
+  "BUILDKITE",
+  "CIRCLECI",
+  "CODESPACES",
+  "DRONE",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "JENKINS_URL",
+  "NETLIFY",
+  "TEAMCITY_VERSION",
+  "TF_BUILD",
+  "TRAVIS",
+  "VERCEL",
+];
+
+interface InstallTelemetryState {
+  lastReportedVersion?: string;
+}
+
+interface PiSettingsDocument {
+  enableInstallTelemetry?: unknown;
+}
+
+function readJsonFile(path: string): unknown {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    return {};
+  }
+}
+
+function isTruthyEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  return value === "1" || value.toLowerCase() === "true" || value.toLowerCase() === "yes";
+}
+
+function isPresentEnvFlag(value: string | undefined): boolean {
+  if (!value) return false;
+  const normalized = value.toLowerCase();
+  return normalized !== "0" && normalized !== "false" && normalized !== "no";
+}
+
+function isCiEnvironment(): boolean {
+  if (isTruthyEnvFlag(process.env.CI)) return true;
+  return CI_ENVIRONMENT_VARIABLES.some((name) => isPresentEnvFlag(process.env[name]));
+}
+
+function isInstallTelemetryEnabled(): boolean {
+  if (isCiEnvironment()) return false;
+  if (isTruthyEnvFlag(process.env.PI_OFFLINE)) return false;
+  if (process.env.PI_TELEMETRY !== undefined) return isTruthyEnvFlag(process.env.PI_TELEMETRY);
+
+  const settings = readJsonFile(join(getAgentDir(), "settings.json")) as PiSettingsDocument;
+  return settings.enableInstallTelemetry !== false;
+}
+
+function getPackageVersion(): string {
+  const packageJson = readJsonFile(fileURLToPath(new URL("../package.json", import.meta.url))) as { version?: unknown };
+  return typeof packageJson.version === "string" && packageJson.version.length > 0 ? packageJson.version : "0.0.0";
+}
+
+function getInstallTelemetryUserAgent(version: string): string {
+  const runtimeVersions = process.versions as NodeJS.ProcessVersions & { bun?: string };
+  const runtime = runtimeVersions.bun ? `bun/${runtimeVersions.bun}` : `node/${process.version}`;
+  return `${PACKAGE_NAME}/${version} (${process.platform}; ${runtime}; ${process.arch})`;
+}
+
+async function reportInstallTelemetryAsync(): Promise<void> {
+  try {
+    if (!isInstallTelemetryEnabled()) return;
+
+    const version = getPackageVersion();
+    const extensionsDir = join(getAgentDir(), "extensions");
+    const statePath = join(extensionsDir, "pi-insomnia-install.json");
+    const state = readJsonFile(statePath) as InstallTelemetryState;
+    if (state.lastReportedVersion === version) return;
+
+    await mkdir(extensionsDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ lastReportedVersion: version }, null, 2)}\n`, "utf8");
+
+    const params = new URLSearchParams({ tool: PACKAGE_NAME, version });
+    await fetch(`${INSTALL_TELEMETRY_URL}?${params.toString()}`, {
+      headers: { "User-Agent": getInstallTelemetryUserAgent(version) },
+      signal: AbortSignal.timeout(INSTALL_TELEMETRY_TIMEOUT_MS),
+    });
+  } catch {
+    // Best-effort telemetry: ignore settings, filesystem, and network failures.
+  }
+}
+
+export function reportInstallTelemetry(): void {
+  void reportInstallTelemetryAsync();
+}

package/src/sleep-inhibitor.ts

@@ -0,0 +1,84 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export const DEFAULT_CAFFEINATE_PATH = "/usr/bin/caffeinate";
+
+export interface MacSleepInhibitorOptions {
+  platform?: NodeJS.Platform;
+  pid?: number;
+  caffeinatePath?: string;
+}
+
+export class MacSleepInhibitor {
+  private readonly platform: NodeJS.Platform;
+  private readonly pid: number;
+  private readonly caffeinatePath: string;
+  private child: ChildProcess | undefined;
+  private activeRequests = 0;
+
+  constructor(options: MacSleepInhibitorOptions = {}) {
+    this.platform = options.platform ?? process.platform;
+    this.pid = options.pid ?? process.pid;
+    this.caffeinatePath = options.caffeinatePath ?? DEFAULT_CAFFEINATE_PATH;
+  }
+
+  get isSupported(): boolean {
+    return this.platform === "darwin";
+  }
+
+  get isActive(): boolean {
+    return this.activeRequests > 0;
+  }
+
+  get isInhibiting(): boolean {
+    return this.child !== undefined;
+  }
+
+  acquire(): boolean {
+    if (!this.isSupported) return false;
+
+    this.activeRequests += 1;
+    this.start();
+    return this.isInhibiting;
+  }
+
+  release(): void {
+    if (!this.isSupported) return;
+
+    if (this.activeRequests > 0) this.activeRequests -= 1;
+    if (this.activeRequests === 0) this.stop();
+  }
+
+  forceStop(): void {
+    this.activeRequests = 0;
+    this.stop();
+  }
+
+  private start(): void {
+    if (this.child) return;
+
+    try {
+      const child = spawn(this.caffeinatePath, ["-i", "-w", String(this.pid)], {
+        stdio: "ignore",
+      });
+
+      this.child = child;
+      child.once("error", () => {
+        if (this.child === child) this.child = undefined;
+      });
+      child.once("exit", () => {
+        if (this.child === child) this.child = undefined;
+      });
+      child.unref();
+    } catch {
+      this.child = undefined;
+    }
+  }
+
+  private stop(): void {
+    const child = this.child;
+    if (!child) return;
+
+    this.child = undefined;
+    if (!child.killed) child.kill("SIGTERM");
+  }
+}