@narumitw/pi-caffeinate 0.49.6 → 0.49.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +50 -46
  2. package/package.json +5 -8
package/README.md CHANGED
@@ -2,15 +2,15 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@narumitw/pi-caffeinate)](https://www.npmjs.com/package/@narumitw/pi-caffeinate) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
4
 
5
- Prevent system or display sleep while Pi is processing a prompt, then release the inhibitor as soon as the run ends.
5
+ Prevent system or display sleep while Pi is running an agent task, then release the inhibitor when the run ends.
6
6
 
7
7
  ## ✨ Features
8
8
 
9
9
  - Starts an OS sleep inhibitor when a Pi run begins and releases it when the run or session ends.
10
- - Supports macOS, Windows, WSL, and Linux with a display-awake default.
11
- - Provides `/caffeinate` controls for the keep-awake mode, current status, and quiet mode.
10
+ - Supports macOS, Windows, WSL, and Linux, with display-awake as the default.
11
+ - Provides `/caffeinate` controls for keep-awake mode and status.
12
12
  - Persists preferences locally and accepts an optional custom inhibitor command.
13
- - Shows activity only while the inhibitor is active and fails safely when no supported mechanism is available.
13
+ - Falls back when possible, warns on partial activation, and reports when no inhibitor is available.
14
14
 
15
15
  ## 📦 Install
16
16
 
@@ -32,19 +32,18 @@ pi -e ./packages/pi-caffeinate
32
32
  ```
33
33
 
34
34
  The package declares `dist/index.ts`, so an unbuilt local checkout must be built before Pi loads the package directory.
35
+ Pi extensions run with the Pi process's user permissions, so install only trusted packages.
35
36
 
36
37
  ## 🚀 Quick start
37
38
 
38
39
  Load the extension and use Pi normally.
39
- During an agent run, pi-caffeinate uses the saved keep-awake mode and defaults to keeping both the system and display awake.
40
- Run `/caffeinate` to open the controls or `/caffeinate status` to inspect the current state.
40
+ During each agent run, pi-caffeinate uses the saved mode and defaults to keeping the system and display awake.
41
+ Run `/caffeinate` for controls or `/caffeinate status` for the current state.
41
42
 
42
43
  ## 🖥️ Supported platforms
43
44
 
44
- The default mode is `display` on every supported OS.
45
- That means pi-caffeinate prevents system sleep, suspend, or hibernate and keeps the screen/display awake.
46
-
47
- Use `/caffeinate sleep` if you want to prevent system sleep while allowing normal display idle behavior such as screen blanking or monitor power-off.
45
+ The default `display` mode prevents system sleep, suspend, or hibernate and keeps the display awake.
46
+ Use `/caffeinate sleep` to prevent system sleep while allowing normal screen blanking or monitor power-off.
48
47
 
49
48
  | Platform | `sleep` mode | `display` mode, default |
50
49
  | --- | --- | --- |
@@ -54,13 +53,13 @@ Use `/caffeinate sleep` if you want to prevent system sleep while allowing norma
54
53
  | Linux with systemd | `systemd-inhibit --what=sleep ... sleep infinity` | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `systemd-inhibit --what=idle:sleep ... sleep infinity` |
55
54
  | Linux without systemd | `caffeinate -ims` when available | D-Bus `org.freedesktop.ScreenSaver.Inhibit` + `caffeinate -dimsu` when available; D-Bus only otherwise |
56
55
 
57
- On Linux, `display` mode requests idle inhibition through the standard `org.freedesktop.ScreenSaver` D-Bus service, trying both `/org/freedesktop/ScreenSaver` and `/ScreenSaver` for desktop compatibility.
58
- The session-bus connection stays open for the whole agent turn.
59
- The inhibition ends when `UnInhibit` is called or the connection closes.
60
- `systemd-inhibit --what=idle:sleep` runs alongside it to preserve logind idle and sleep inhibition.
61
- If no ScreenSaver service is available, pi-caffeinate keeps the systemd blocker or `caffeinate` fallback and reports a partial-activation warning.
62
- If only D-Bus is available, pi-caffeinate reports partial activation because desktop idle is inhibited but direct system suspend may remain possible.
63
- D-Bus method calls use short deadlines, and stop or shutdown aborts an in-flight acquisition before closing its session-bus connection.
56
+ On Linux, `display` mode requests idle inhibition from `org.freedesktop.ScreenSaver` over D-Bus.
57
+ It tries `/org/freedesktop/ScreenSaver` and `/ScreenSaver` for desktop compatibility and keeps the session-bus connection open for the agent turn.
58
+ Calling `UnInhibit` or closing the connection releases the request.
59
+ `systemd-inhibit --what=idle:sleep` runs alongside D-Bus to preserve logind idle and sleep inhibition.
60
+ If the ScreenSaver service is unavailable, pi-caffeinate keeps the systemd or `caffeinate` blocker and warns that activation is partial.
61
+ If only D-Bus is available, it warns that direct system suspend may remain possible.
62
+ D-Bus calls have 2-second deadlines, and stop or shutdown aborts an in-progress acquisition before closing the connection.
64
63
 
65
64
  If no supported inhibitor is available, the extension stays loaded and reports that caffeinate is unavailable.
66
65
 
@@ -70,8 +69,9 @@ If no supported inhibitor is available, the extension stays loaded and reports t
70
69
  /caffeinate
71
70
  ```
72
71
 
73
- Opens standard keep-awake controls in TUI or RPC mode.
74
- Print and JSON modes reject the interactive menu observably; use the direct `status`, `sleep`, `display`, `stop`, or `help` routes instead.
72
+ Opens keep-awake controls in TUI or RPC mode.
73
+ Print and JSON modes reject the interactive menu.
74
+ Direct routes avoid interactive UI, but Pi's print and JSON modes do not display their notification feedback.
75
75
 
76
76
  ```text
77
77
  /caffeinate display
@@ -91,21 +91,29 @@ If an inhibitor is currently active, it is restarted so the new mode applies imm
91
91
  /caffeinate status
92
92
  ```
93
93
 
94
- Shows whether an inhibitor is active, unavailable, disabled, or idle.
95
- The status includes the current mode, quiet mode, and settings file path.
94
+ Shows whether the inhibitor is active, unavailable, disabled, or idle.
95
+ The result includes the mode, quiet-mode state, and settings path.
96
96
 
97
97
  ```text
98
98
  /caffeinate mode
99
99
  ```
100
100
 
101
- Opens the standard keep-awake mode selector in TUI or RPC mode.
102
- Escape closes the selector.
101
+ Opens the keep-awake mode selector in TUI or RPC mode.
102
+ Escape closes it.
103
103
 
104
104
  ```text
105
105
  /caffeinate stop
106
106
  ```
107
107
 
108
- Releases any active inhibitor until Pi starts another agent run.
108
+ Releases the active inhibitor until Pi starts another agent run.
109
+
110
+ ```text
111
+ /caffeinate help
112
+ ```
113
+
114
+ Shows the canonical command routes.
115
+ In TUI and RPC mode, unknown commands and trailing text show a rejection with the command guide.
116
+ Compatibility aliases are `screen` for `display`, `system` for `sleep`, `off` for `stop`, and `config` or `settings` for `mode`.
109
117
 
110
118
  ## ⚙️ Settings
111
119
 
@@ -127,21 +135,23 @@ Example:
127
135
  }
128
136
  ```
129
137
 
130
- Set `"quiet": true` to hide the routine `Keeping computer awake (...)` and `Released pi-caffeinate (agent finished)` lifecycle notifications and keep the `caffeinate` status item clear while active or unavailable.
131
- Quiet mode does not hide warnings or explicit feedback from `/caffeinate` commands such as `status`, mode changes, help, and manual stop.
138
+ Set `"quiet": true` to hide routine start and release notifications and clear the `caffeinate` status item while active or unavailable.
139
+ Quiet mode does not hide warnings or explicit command feedback.
132
140
  It defaults to `false` when omitted.
133
- The file is read at startup and on `/reload`; run `/reload` after editing it in a running Pi session before using mode commands.
141
+ The file is read at startup and on `/reload`.
142
+ After editing it in a running session, run `/reload` before using mode commands.
134
143
 
135
- Missing, invalid, or deleted settings default back to `display` mode with quiet mode disabled on every supported OS.
144
+ Missing, invalid, or deleted settings use `display` mode with quiet mode off.
136
145
  A missing file stays absent until the first successful mode change.
137
146
  Within one Pi process, mode saves run in invocation order, reread the latest valid document, and preserve unknown fields.
138
- Malformed JSON or an invalid recognized field blocks mode saves until repaired instead of being overwritten.
139
- A failed save keeps the prior runtime mode; if restarting an active inhibitor fails after publication, the extension restores the prior saved mode and inhibitor behavior or reports an explicit rollback failure.
140
-
141
- Compatibility: older versions used `pi-caffeinate-settings.json`.
142
- A legacy-only file remains readable with a warning and is never modified automatically; rename it to `pi-caffeinate.json`.
143
- The first subsequent settings save writes the canonical file.
144
- If both files exist, `pi-caffeinate.json` wins and the legacy file is ignored.
147
+ Malformed JSON or an invalid recognized field blocks saves until repaired.
148
+ A failed save keeps the previous runtime mode.
149
+ If applying a published mode fails while an inhibitor is active, the extension restores the previous saved mode and inhibitor or reports a rollback failure.
150
+
151
+ Older versions used `pi-caffeinate-settings.json`.
152
+ A legacy-only file remains readable with a warning and is not modified automatically; rename it to `pi-caffeinate.json`.
153
+ The next settings save writes the canonical file.
154
+ If both files exist, `pi-caffeinate.json` takes precedence.
145
155
  The legacy filename is deprecated and will be removed in a future major release.
146
156
 
147
157
  ### Environment variables
@@ -158,8 +168,8 @@ Use a custom inhibitor command:
158
168
  PI_CAFFEINATE_COMMAND='systemd-inhibit --what=idle:sleep --why="pi running" --mode=block sleep infinity' pi
159
169
  ```
160
170
 
161
- The custom command is parsed with shell-like quoting and is run directly without a shell.
162
- `PI_CAFFEINATE_COMMAND` takes precedence over the saved mode; `/caffeinate status` reports when a custom command is active.
171
+ The custom command uses shell-like argument parsing but runs directly without a shell.
172
+ `PI_CAFFEINATE_COMMAND` overrides the saved mode, and `/caffeinate status` reports the override.
163
173
 
164
174
  Deprecated: `PI_CAFFEINATE_ICON` still works for now.
165
175
  If you use `@narumitw/pi-statusline`, move the icon to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline.json`:
@@ -173,19 +183,13 @@ If you use `@narumitw/pi-statusline`, move the icon to `${PI_CODING_AGENT_DIR:-~
173
183
  ```
174
184
 
175
185
  Without `@narumitw/pi-statusline`, keep using `PI_CAFFEINATE_ICON` during the compatibility window.
176
- In `pi-statusline.json`, use an empty string to show the caffeinate status without an icon.
177
-
178
- ## 🧠 Why use pi-caffeinate?
179
-
180
- AI coding agents often run tool-heavy tasks that take several minutes.
181
- `pi-caffeinate` keeps your machine awake during active Pi work, helping browser automation, local builds, test runs, code generation, and long prompts finish reliably.
186
+ In `pi-statusline.json`, use an empty string to show caffeinate status without an icon.
182
187
 
183
- The default display-awake mode prioritizes uninterrupted long-running Pi work across platforms, including Linux desktops that require idle inhibition to prevent automatic suspend.
184
- Use `/caffeinate sleep` (shown as `system-awake` in status output) when you prefer normal screen power saving and your system does not need idle inhibition to keep Pi running.
188
+ Status output calls `display` mode `display-awake` and `sleep` mode `system-awake`.
185
189
 
186
190
  ## 📦 Dependencies
187
191
 
188
- On Linux, `display` mode uses the `dbus-native` package (pure JavaScript, no native build step) to call `org.freedesktop.ScreenSaver` on the session bus.
192
+ On Linux, `display` mode uses the pure-JavaScript `dbus-native` package to call `org.freedesktop.ScreenSaver` on the session bus.
189
193
 
190
194
  ## 🗂️ Package layout
191
195
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-caffeinate",
3
- "version": "0.49.6",
3
+ "version": "0.49.7",
4
4
  "description": "Pi extension that keeps the computer awake while the agent is running.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -24,9 +24,6 @@
24
24
  "./dist/index.ts"
25
25
  ]
26
26
  },
27
- "piExtension": {
28
- "lifecycle": "stable"
29
- },
30
27
  "scripts": {
31
28
  "build": "node scripts/build-runtime.mjs",
32
29
  "check": "npm run build && biome check . && npm run typecheck",
@@ -38,9 +35,9 @@
38
35
  "@earendil-works/pi-coding-agent": "*"
39
36
  },
40
37
  "devDependencies": {
41
- "@biomejs/biome": "2.5.10",
42
- "@earendil-works/pi-coding-agent": "0.84.3",
43
- "@types/node": "26.2.0",
38
+ "@biomejs/biome": "2.5.11",
39
+ "@earendil-works/pi-coding-agent": "0.84.4",
40
+ "@types/node": "26.4.0",
44
41
  "esbuild": "0.28.2",
45
42
  "typescript": "7.0.2"
46
43
  },
@@ -50,7 +47,7 @@
50
47
  "directory": "packages/pi-caffeinate"
51
48
  },
52
49
  "dependencies": {
53
- "@narumitw/pi-tui-kit": "^0.49.1",
50
+ "@narumitw/pi-tui-kit": "^0.59.0",
54
51
  "dbus-native": "^0.15.2"
55
52
  }
56
53
  }