Prevent Sleep

Instructions

Implementation Reference

• src/system/tools.ts:538-556 (handler)

  Handler function for the 'prevent_sleep' tool. Kills any previous caffeinate processes, runs the JXA script to start a new caffeinate process, tracks its PID, and returns the result.

    async ({ seconds }) => {
      try {
        // Kill any previous caffeinate processes before starting a new one
        for (const pid of caffeinatePids) {
          try {
            process.kill(pid);
          } catch {
            /* already exited */
          }
        }
        caffeinatePids.clear();
        const result = await runJxa<{ action: string; pid: number; seconds: number }>(preventSleepScript(seconds));
        caffeinatePids.add(result.pid);
        return ok(result);
      } catch (e) {
        return errJxaFor("prevent sleep", e);
      }
    },
  );

• src/system/tools.ts:515-536 (schema)

  Registration of the 'prevent_sleep' tool with title, description, input schema (seconds: number, optional, default 3600, max 86400), and annotations.

  server.registerTool(
    "prevent_sleep",
    {
      title: "Prevent Sleep",
      description:
        "Prevent the Mac from sleeping for a specified duration using caffeinate. Returns the process PID for cancellation.",
      inputSchema: {
        seconds: z
          .number()
          .int()
          .min(1)
          .max(86400)
          .optional()
          .default(3600)
          .describe("Duration in seconds (default: 3600 = 1 hour, max: 86400 = 24 hours)"),
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },

• src/system/tools.ts:515-556 (registration)

  Registration call for 'prevent_sleep' tool on the MCP server via server.registerTool().

  server.registerTool(
    "prevent_sleep",
    {
      title: "Prevent Sleep",
      description:
        "Prevent the Mac from sleeping for a specified duration using caffeinate. Returns the process PID for cancellation.",
      inputSchema: {
        seconds: z
          .number()
          .int()
          .min(1)
          .max(86400)
          .optional()
          .default(3600)
          .describe("Duration in seconds (default: 3600 = 1 hour, max: 86400 = 24 hours)"),
      },
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
    },
    async ({ seconds }) => {
      try {
        // Kill any previous caffeinate processes before starting a new one
        for (const pid of caffeinatePids) {
          try {
            process.kill(pid);
          } catch {
            /* already exited */
          }
        }
        caffeinatePids.clear();
        const result = await runJxa<{ action: string; pid: number; seconds: number }>(preventSleepScript(seconds));
        caffeinatePids.add(result.pid);
        return ok(result);
      } catch (e) {
        return errJxaFor("prevent sleep", e);
      }
    },
  );

• src/system/scripts.ts:282-290 (helper)

  Helper function 'preventSleepScript' that generates a JXA script string. The script runs 'caffeinate -t <seconds>' in the shell and returns the PID and action info via JSON.

  export function preventSleepScript(seconds: number): string {
    const secs = Math.max(1, Math.round(seconds));
    return `
      const app = Application.currentApplication();
      app.includeStandardAdditions = true;
      const pid = app.doShellScript('caffeinate -t ${secs} & echo $!');
      JSON.stringify({action: 'prevent_sleep', pid: parseInt(pid.trim()), seconds: ${secs}});
    `;
  }

• src/system/tools.ts:38-50 (helper)

  Module-level Set<number> 'caffeinatePids' to track active caffeinate PIDs, with cleanup on server exit via process.on('exit') handler.

  const caffeinatePids = new Set<number>();
  
  // Clean up ALL orphaned caffeinate processes on server exit
  process.on("exit", () => {
    for (const pid of caffeinatePids) {
      try {
        process.kill(pid);
      } catch {
        /* already exited */
      }
    }
    caffeinatePids.clear();
  });