@mystilleef/pi-subagent 0.9.0 → 0.10.2

package/src/child/termination.ts

@@ -1,4 +1,5 @@
 import type { ChildProcess } from "node:child_process";
+import { spawn } from "node:child_process";
 
 export type TerminationSignal = "SIGTERM" | "SIGKILL";
 
@@ -12,6 +13,39 @@ export type TerminationMetadata = {
   fallbackCause?: string | undefined;
 };
 
+export type SleepInhibitorHandle = {
+  release: () => Promise<void>;
+};
+
+export type SleepInhibitorAdapterHandle = {
+  release?: () => unknown;
+};
+
+export type SleepInhibitorAdapter = {
+  supported?: () => boolean | Promise<boolean>;
+  acquire: (pid: number) => unknown;
+};
+
+export type SleepInhibitorHelperProcess = {
+  exitCode?: number | null;
+  signalCode?: NodeJS.Signals | string | null;
+  kill?: (signal?: NodeJS.Signals | number) => unknown;
+  on?: (event: "error", listener: (error: Error) => void) => unknown;
+  unref?: () => unknown;
+};
+
+export type HostSleepInhibitorAdapterOptions = {
+  platform?: NodeJS.Platform;
+  environment?: Partial<NodeJS.ProcessEnv>;
+  getEnvironment?: () => Partial<NodeJS.ProcessEnv>;
+  commandExists?: (command: string) => boolean | Promise<boolean>;
+  spawnHelper?: (
+    command: string,
+    args: string[],
+    options: { stdio: "ignore"; detached: true },
+  ) => SleepInhibitorHelperProcess;
+};
+
 type TimerHandle = unknown;
 
 type TerminationState = {
@@ -43,6 +77,15 @@ export type TerminateChildProcessOptions = {
 };
 
 const DEFAULT_TIMEOUT_MS = 4_000;
+const CAFFEINATE_COMMAND = "caffeinate";
+const SYSTEMD_INHIBIT_COMMAND = "systemd-inhibit";
+const GNOME_SESSION_INHIBIT_COMMAND = "gnome-session-inhibit";
+const KDE_INHIBIT_COMMAND = "kde-inhibit";
+const POWERSHELL_COMMAND = "powershell.exe";
+const SHELL_COMMAND = "/bin/sh";
+const noopSleepInhibitorHandle: SleepInhibitorHandle = {
+  async release() {},
+};
 const terminationStates = new WeakMap<ChildProcess, TerminationState>();
 
 export function getProcessTreeSpawnOptions(
@@ -52,12 +95,284 @@ export function getProcessTreeSpawnOptions(
   return tree && platform !== "win32" ? { detached: true } : {};
 }
 
+export function isFinitePid(pid: unknown): pid is number {
+  return typeof pid === "number" && Number.isFinite(pid);
+}
+
+function isAdapterHandle(
+  handle: unknown,
+): handle is SleepInhibitorAdapterHandle {
+  return typeof handle === "object" && handle !== null;
+}
+
+function makeSleepInhibitorHandle(
+  adapterHandle: SleepInhibitorAdapterHandle,
+): SleepInhibitorHandle {
+  let released = false;
+  return {
+    async release() {
+      if (released) return;
+      released = true;
+      try {
+        await adapterHandle.release?.();
+      } catch {
+        /* adapter release failures are non-fatal */
+      }
+    },
+  };
+}
+
+async function defaultCommandExists(command: string): Promise<boolean> {
+  try {
+    return await new Promise<boolean>((resolve) => {
+      const child = spawn("/bin/sh", ["-c", `command -v ${command}`], {
+        stdio: ["ignore", "ignore", "ignore"],
+      });
+      child.on("error", () => resolve(false));
+      child.on("exit", (code) => resolve(code === 0));
+    });
+  } catch {
+    /* missing, non-executable, failed, or throwing lookups return false */
+    return false;
+  }
+}
+
+function helperHasEnded(helper: SleepInhibitorHelperProcess): boolean {
+  return (
+    (helper.exitCode ?? null) !== null || (helper.signalCode ?? null) !== null
+  );
+}
+
+function makeHelperHandle(
+  helper: SleepInhibitorHelperProcess,
+): SleepInhibitorAdapterHandle {
+  helper.on?.("error", () => undefined);
+  helper.unref?.();
+  return {
+    release() {
+      if (helperHasEnded(helper)) return;
+      helper.kill?.("SIGTERM");
+    },
+  };
+}
+
+function getDesktopTokens(desktop: string | undefined): Set<string> {
+  return new Set(
+    (desktop ?? "")
+      .toLowerCase()
+      .split(/[\s:;,+/]+/u)
+      .filter(Boolean),
+  );
+}
+
+function getLinuxDesktopTokens(
+  getEnvironment: () => Partial<NodeJS.ProcessEnv>,
+): Set<string> {
+  try {
+    return getDesktopTokens(getEnvironment()["XDG_CURRENT_DESKTOP"]);
+  } catch {
+    return new Set<string>();
+  }
+}
+
+function hasGnomeCompatibleDesktop(tokens: Set<string>): boolean {
+  return tokens.has("gnome") || tokens.has("ubuntu");
+}
+
+function hasKdeCompatibleDesktop(tokens: Set<string>): boolean {
+  return tokens.has("kde") || tokens.has("plasma");
+}
+
+async function commandExistsSafely(
+  commandExists: (command: string) => boolean | Promise<boolean>,
+  command: string,
+): Promise<boolean> {
+  try {
+    return await commandExists(command);
+  } catch {
+    return false;
+  }
+}
+
+function makePidPollingShellArgs(pid: number): string[] {
+  return [
+    SHELL_COMMAND,
+    "-c",
+    `while kill -0 ${pid} 2>/dev/null && [ "$(cut -d' ' -f4 /proc/$$/stat 2>/dev/null)" != "1" ]; do sleep 1; done`,
+  ];
+}
+
+function makeSystemdInhibitArgs(pid: number): string[] {
+  return [
+    "--what=sleep:idle",
+    "--who=pi-subagent",
+    "--why=subagent running",
+    "--mode=block",
+    ...makePidPollingShellArgs(pid),
+  ];
+}
+
+function makeGnomeSessionInhibitArgs(pid: number): string[] {
+  return [
+    "--app-id=pi-subagent",
+    "--inhibit=suspend:idle",
+    "--reason=subagent running",
+    ...makePidPollingShellArgs(pid),
+  ];
+}
+
+function makeKdeInhibitArgs(pid: number): string[] {
+  return ["--power", "--screenSaver", ...makePidPollingShellArgs(pid)];
+}
+
+function makePowerShellInhibitArgs(pid: number): string[] {
+  const script = [
+    "Add-Type -Namespace PiSubagent -Name NativeMethods -MemberDefinition '[DllImport(\"kernel32.dll\")] public static extern uint SetThreadExecutionState(uint esFlags);'",
+    "[PiSubagent.NativeMethods]::SetThreadExecutionState(0x80000001) | Out-Null",
+    `try { while (Get-Process -Id ${pid} -ErrorAction SilentlyContinue) { Start-Sleep -Seconds 1 } } finally { [PiSubagent.NativeMethods]::SetThreadExecutionState(0x80000000) | Out-Null }`,
+  ].join("; ");
+  return ["-NonInteractive", "-Command", script];
+}
+
+async function acquireLinuxSleepInhibitor(
+  pid: number,
+  getEnvironment: () => Partial<NodeJS.ProcessEnv>,
+  commandExists: (command: string) => boolean | Promise<boolean>,
+  spawnHelper: (
+    command: string,
+    args: string[],
+    options: { stdio: "ignore"; detached: true },
+  ) => SleepInhibitorHelperProcess,
+): Promise<SleepInhibitorAdapterHandle> {
+  const spawnSingleHelper = (
+    command: string,
+    args: string[],
+  ): SleepInhibitorAdapterHandle => {
+    try {
+      return makeHelperHandle(
+        spawnHelper(command, args, {
+          stdio: "ignore",
+          detached: true,
+        }),
+      );
+    } catch {
+      /* chosen-helper spawn failures degrade to empty handle */
+      return {};
+    }
+  };
+  const tokens = getLinuxDesktopTokens(getEnvironment);
+  if (
+    hasGnomeCompatibleDesktop(tokens) &&
+    (await commandExistsSafely(commandExists, GNOME_SESSION_INHIBIT_COMMAND))
+  )
+    return spawnSingleHelper(
+      GNOME_SESSION_INHIBIT_COMMAND,
+      makeGnomeSessionInhibitArgs(pid),
+    );
+  if (
+    hasKdeCompatibleDesktop(tokens) &&
+    (await commandExistsSafely(commandExists, KDE_INHIBIT_COMMAND))
+  )
+    return spawnSingleHelper(KDE_INHIBIT_COMMAND, makeKdeInhibitArgs(pid));
+  if (await commandExistsSafely(commandExists, SYSTEMD_INHIBIT_COMMAND))
+    return spawnSingleHelper(
+      SYSTEMD_INHIBIT_COMMAND,
+      makeSystemdInhibitArgs(pid),
+    );
+  return {};
+}
+
+export function makeHostSleepInhibitorAdapter(
+  options: HostSleepInhibitorAdapterOptions = {},
+): SleepInhibitorAdapter {
+  const platform = options.platform ?? process.platform;
+  const commandExists = options.commandExists ?? defaultCommandExists;
+  const getEnvironment =
+    options.getEnvironment ?? (() => options.environment ?? process.env);
+  const spawnHelper =
+    options.spawnHelper ??
+    ((command, args, spawnOptions) => spawn(command, args, spawnOptions));
+  return {
+    async supported() {
+      if (platform === "win32") return true;
+      if (platform === "darwin")
+        return commandExistsSafely(commandExists, CAFFEINATE_COMMAND);
+      if (platform === "linux") {
+        const tokens = getLinuxDesktopTokens(getEnvironment);
+        if (
+          hasGnomeCompatibleDesktop(tokens) &&
+          (await commandExistsSafely(
+            commandExists,
+            GNOME_SESSION_INHIBIT_COMMAND,
+          ))
+        )
+          return true;
+        if (
+          hasKdeCompatibleDesktop(tokens) &&
+          (await commandExistsSafely(commandExists, KDE_INHIBIT_COMMAND))
+        )
+          return true;
+        return commandExistsSafely(commandExists, SYSTEMD_INHIBIT_COMMAND);
+      }
+      return false;
+    },
+    acquire(pid) {
+      if (platform === "darwin") {
+        const helper = spawnHelper(
+          CAFFEINATE_COMMAND,
+          ["-dimsu", "-w", String(pid)],
+          { stdio: "ignore", detached: true },
+        );
+        return makeHelperHandle(helper);
+      }
+      if (platform === "linux") {
+        return acquireLinuxSleepInhibitor(
+          pid,
+          getEnvironment,
+          commandExists,
+          spawnHelper,
+        );
+      }
+      if (platform === "win32") {
+        const helper = spawnHelper(
+          POWERSHELL_COMMAND,
+          makePowerShellInhibitArgs(pid),
+          {
+            stdio: "ignore",
+            detached: true,
+          },
+        );
+        return makeHelperHandle(helper);
+      }
+      return {};
+    },
+  };
+}
+
+export async function acquireChildSleepInhibitor(
+  pid: unknown,
+  adapter?: SleepInhibitorAdapter,
+): Promise<SleepInhibitorHandle> {
+  if (!isFinitePid(pid) || !adapter) return noopSleepInhibitorHandle;
+  try {
+    if ((await adapter.supported?.()) === false)
+      return noopSleepInhibitorHandle;
+    const handle = await adapter.acquire(pid);
+    return isAdapterHandle(handle)
+      ? makeSleepInhibitorHandle(handle)
+      : noopSleepInhibitorHandle;
+  } catch {
+    /* unsupported platforms or acquisition failures degrade to no-op handle */
+    return noopSleepInhibitorHandle;
+  }
+}
+
 function childHasExited(proc: ChildProcess): boolean {
   return proc.exitCode !== null || proc.signalCode != null;
 }
 
 function hasPid(proc: ChildProcess): proc is ChildProcess & { pid: number } {
-  return typeof proc.pid === "number" && Number.isFinite(proc.pid);
+  return isFinitePid(proc.pid);
 }
 
 function settleState(state: TerminationState): void {

package/src/env.d.ts

@@ -9,5 +9,7 @@ declare namespace NodeJS {
     PI_SUBAGENT_AGENT_END_GRACE_MS?: string;
     PI_SUBAGENT_MAX_STDERR_BYTES?: string;
     PI_SUBAGENT_DEBUG_ENABLED?: string;
+    PI_SUBAGENT_DESKTOP_NOTIFICATIONS?: string;
+    PI_SUBAGENT_NOTIFY_PER_JOB?: string;
   }
 }

package/src/notification/delivery.ts

@@ -0,0 +1,231 @@
+/**
+ * Platform delivery implementations for desktop notifications.
+ *
+ * Delivers notification requests through safe native commands with
+ * async bounded subprocess handling and silent degradation.
+ */
+
+import { spawn } from "node:child_process";
+import { access, stat } from "node:fs/promises";
+import { join } from "node:path";
+import type { NotificationRequest } from "./desktop-notification.js";
+
+const LINUX_NOTIFY_SEND = "notify-send";
+
+export type DeliveryDependencies = {
+  platform?: NodeJS.Platform;
+  commandExists?: (command: string) => boolean | Promise<boolean>;
+  spawnProcess?: (
+    command: string,
+    args: string[],
+    options: { stdio: "ignore" },
+  ) => { unref?: () => void };
+};
+
+type SpawnProcess = NonNullable<DeliveryDependencies["spawnProcess"]>;
+
+type NotificationCommand = {
+  command: string;
+  args: string[];
+};
+
+type BuildNotificationCommand = (
+  request: NotificationRequest,
+) => NotificationCommand;
+
+type NotificationDelivery = (
+  request: NotificationRequest,
+  deps?: DeliveryDependencies,
+) => Promise<void>;
+
+export async function defaultCommandExists(command: string): Promise<boolean> {
+  const pathEnv = process.env.PATH;
+  if (!pathEnv) return false;
+  const entries = pathEnv.split(":").filter((e) => e.length > 0);
+  for (const entry of entries) {
+    const dir = entry.replace(/\/+$/, "");
+    const candidate = join(dir, command);
+    try {
+      const info = await stat(candidate);
+      if (!info.isFile()) continue;
+      await access(candidate, 1); // X_OK
+      return true;
+    } catch {}
+  }
+  return false;
+}
+
+let defaultDeliveryDeps: DeliveryDependencies | undefined;
+
+export function setDefaultDeliveryDeps(
+  deps: DeliveryDependencies | undefined,
+): void {
+  defaultDeliveryDeps = deps;
+}
+
+export function resetDefaultDeliveryDeps(): void {
+  defaultDeliveryDeps = undefined;
+}
+
+let notifySendAvailable: boolean | undefined;
+
+export function resetNotifySendCache(): void {
+  notifySendAvailable = undefined;
+}
+
+async function checkNotifySendExists(
+  commandExists: (command: string) => boolean | Promise<boolean>,
+): Promise<boolean> {
+  if (notifySendAvailable !== undefined) return notifySendAvailable;
+  try {
+    notifySendAvailable = await commandExists(LINUX_NOTIFY_SEND);
+  } catch {
+    notifySendAvailable = false;
+  }
+  return notifySendAvailable;
+}
+
+function escapeLinuxArgs(request: NotificationRequest): string[] {
+  const args: string[] = [];
+  if (request.urgency === "critical") args.push("--urgency=critical");
+  args.push(`--expire-time=${request.timeoutMs}`);
+  args.push(request.title);
+  args.push(request.body);
+  return args;
+}
+
+function escapeAppleScriptString(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function buildAppleScript(request: NotificationRequest): string {
+  const title = escapeAppleScriptString(request.title);
+  const body = escapeAppleScriptString(request.body);
+  return `display notification "${body}" with title "${title}"`;
+}
+
+function escapePowerShellString(value: string): string {
+  return value.replace(/'/g, "''");
+}
+
+function buildPowerShellScript(request: NotificationRequest): string {
+  const title = escapePowerShellString(request.title);
+  const body = escapePowerShellString(request.body);
+  return [
+    "Add-Type -AssemblyName System.Windows.Forms",
+    `$notify = New-Object System.Windows.Forms.NotifyIcon`,
+    `$notify.Icon = [System.Drawing.SystemIcons]::Information`,
+    `$notify.Visible = $true`,
+    `$notify.ShowBalloonTip(${request.timeoutMs}, '${title}', '${body}', [System.Windows.Forms.ToolTipIcon]::Info)`,
+    `Start-Sleep -Milliseconds ${request.timeoutMs + 500}`,
+    `$notify.Dispose()`,
+  ].join("; ");
+}
+
+function getSpawnProcess(deps: DeliveryDependencies): SpawnProcess {
+  return deps.spawnProcess ?? ((cmd, args, opts) => spawn(cmd, args, opts));
+}
+
+function shouldDeliverToPlatform(
+  deps: DeliveryDependencies,
+  platform: NodeJS.Platform,
+): boolean {
+  return (deps.platform ?? process.platform) === platform;
+}
+
+function runDetached(
+  spawnFn: SpawnProcess,
+  command: string,
+  args: string[],
+): void {
+  try {
+    const child = spawnFn(command, args, { stdio: "ignore" });
+    child.unref?.();
+  } catch {
+    /* spawn failures degrade silently */
+  }
+}
+
+async function deliverPlatformNotification(
+  request: NotificationRequest,
+  deps: DeliveryDependencies,
+  platform: NodeJS.Platform,
+  buildCommand: BuildNotificationCommand,
+): Promise<void> {
+  if (!shouldDeliverToPlatform(deps, platform)) return;
+  const { command, args } = buildCommand(request);
+  runDetached(getSpawnProcess(deps), command, args);
+}
+
+export async function deliverLinuxNotification(
+  request: NotificationRequest,
+  deps: DeliveryDependencies = {},
+): Promise<void> {
+  if (!shouldDeliverToPlatform(deps, "linux")) return;
+  const commandExists = deps.commandExists ?? defaultCommandExists;
+  const available = await checkNotifySendExists(commandExists);
+  if (!available) return;
+  runDetached(
+    getSpawnProcess(deps),
+    LINUX_NOTIFY_SEND,
+    escapeLinuxArgs(request),
+  );
+}
+
+export async function deliverMacOSNotification(
+  request: NotificationRequest,
+  deps: DeliveryDependencies = {},
+): Promise<void> {
+  await deliverPlatformNotification(
+    request,
+    deps,
+    "darwin",
+    (notification) => ({
+      command: "osascript",
+      args: ["-e", buildAppleScript(notification)],
+    }),
+  );
+}
+
+export async function deliverWindowsNotification(
+  request: NotificationRequest,
+  deps: DeliveryDependencies = {},
+): Promise<void> {
+  await deliverPlatformNotification(request, deps, "win32", (notification) => ({
+    command: "powershell.exe",
+    args: [
+      "-NoProfile",
+      "-NonInteractive",
+      "-WindowStyle",
+      "Hidden",
+      "-Command",
+      buildPowerShellScript(notification),
+    ],
+  }));
+}
+
+const PLATFORM_DELIVERIES: Partial<
+  Record<NodeJS.Platform, NotificationDelivery>
+> = {
+  linux: deliverLinuxNotification,
+  darwin: deliverMacOSNotification,
+  win32: deliverWindowsNotification,
+};
+
+function resolveDeliveryDeps(
+  explicit?: DeliveryDependencies,
+): DeliveryDependencies {
+  if (!defaultDeliveryDeps) return explicit ?? {};
+  if (!explicit) return defaultDeliveryDeps;
+  return { ...defaultDeliveryDeps, ...explicit };
+}
+
+export async function deliverNotification(
+  request: NotificationRequest,
+  deps?: DeliveryDependencies,
+): Promise<void> {
+  const resolved = resolveDeliveryDeps(deps);
+  const platform = resolved.platform ?? process.platform;
+  const deliver = PLATFORM_DELIVERIES[platform];
+  if (deliver) await deliver(request, resolved);
+}

package/src/notification/desktop-notification.ts

@@ -0,0 +1,73 @@
+/**
+ * Desktop notification model, formatting, and environment parsing.
+ *
+ * Defines the notification request shape, message text generation,
+ * duration formatting, and opt-out env parsing behind a small testable
+ * boundary. No platform delivery logic lives here.
+ */
+
+import { formatElapsed } from "../progress/progress-format.js";
+import type {
+  ProgressStatus,
+  SubagentProgressState,
+} from "../progress/progress-state.js";
+
+export const NOTIFICATION_TITLE = "Pi Subagent";
+
+export interface NotificationRequest {
+  title: string;
+  body: string;
+  urgency: "normal" | "critical";
+  timeoutMs: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export function isDesktopNotificationsEnabled(
+  env?: Partial<NodeJS.ProcessEnv>,
+): boolean {
+  const raw =
+    env?.PI_SUBAGENT_DESKTOP_NOTIFICATIONS ??
+    process.env.PI_SUBAGENT_DESKTOP_NOTIFICATIONS;
+  if (raw === undefined || raw === "") return true;
+  return raw !== "0";
+}
+
+export function isPerJobNotificationEnabled(
+  env?: Partial<NodeJS.ProcessEnv>,
+): boolean {
+  const raw =
+    env?.PI_SUBAGENT_NOTIFY_PER_JOB ?? process.env.PI_SUBAGENT_NOTIFY_PER_JOB;
+  return raw === "1";
+}
+
+export function deriveDurationMs(
+  state: SubagentProgressState,
+  now?: () => number,
+): number {
+  if (state.durationMs !== undefined) return state.durationMs;
+  return (now ? now() : Date.now()) - state.startTime;
+}
+
+export function formatNotificationBody(
+  agent: string,
+  status: ProgressStatus,
+  durationMs: number,
+): string {
+  const duration = formatElapsed(durationMs);
+  if (status === "error") return `${agent} failed after ${duration}`;
+  return `${agent} finished in ${duration}`;
+}
+
+export function buildNotificationRequest(
+  state: SubagentProgressState,
+  now?: () => number,
+): NotificationRequest {
+  const durationMs = deriveDurationMs(state, now);
+  return {
+    title: NOTIFICATION_TITLE,
+    body: formatNotificationBody(state.agent, state.status, durationMs),
+    urgency: state.status === "error" ? "critical" : "normal",
+    timeoutMs: DEFAULT_TIMEOUT_MS,
+  };
+}

package/src/orchestration/run-command.ts

@@ -4,7 +4,7 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { startSubagentJob } from "./subagent-orchestrator.js";
 
-export function parseRunArgs(
+function parseRunArgs(
   args: string,
 ): { agentName: string; task: string; debug: boolean } | undefined {
   const input = args.trim();