@pi-archimedes/notify 2.5.1 → 2.6.2

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 +35 -34
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -1,59 +1,60 @@
1
1
  # @pi-archimedes/notify
2
2
 
3
- Delayed desktop notifications with circuit breaker for the [Pi coding agent](https://github.com/earendil-works/pi).
3
+ **Step away without losing track.**
4
4
 
5
- Get notified when Pi finishes long tasks or needs an answer, without constant popup spam thanks to delayed firing and raw keypress circuit breaking. You can safely switch windows while long-running jobs execute, knowing a desktop alert will trigger only if you aren't already actively typing in the terminal.
6
-
7
- ## What you get
8
-
9
- - **Delayed notification** — fires only after a configurable period of inactivity (default 30s), so you're not spammed when actively working
10
- - **Circuit breaker** — any keystroke immediately cancels a pending notification via raw terminal input listening
11
- - **Terminal-aware dispatch** — auto-detects your terminal and uses the optimal protocol (OSC 99, OSC 9, OSC 777, or PowerShell toasts)
12
- - **tmux passthrough** — all sequences wrapped via DCS for correct rendering inside tmux
13
- - **Per-trigger toggles** — independently enable/disable notifications for task completion and unanswered questions
14
- - **Pi-native triggers** — keyed on pi's `agent_settled` and `ui_prompt_start` lifecycle events, so task completion works and *any* blocking extension prompt (ask, sudo, mcp OAuth) can hold your attention
5
+ Leave the terminal for a coffee. When the work has actually settled — or something needs your decision — notify tells you, once, after a short delay. Type anything and the pending alert is cancelled; there's no inactivity scrutiny, no focus tracking. Keystrokes are the only signal.
15
6
 
16
7
  ## Install
17
8
 
9
+ Standalone:
10
+
18
11
  ```bash
19
12
  pi install npm:@pi-archimedes/notify
20
13
  ```
21
14
 
22
- Or install full meta package:
15
+ Or the full suite instead:
23
16
 
24
17
  ```bash
25
18
  pi install npm:pi-archimedes
26
19
  ```
27
20
 
28
- ## Usage
21
+ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0:
29
22
 
30
- When the agent's run has settled (`agent_settled`) or an extension opens a blocking prompt (`ui_prompt_start` — ask, sudo, mcp OAuth), a timer starts. If you don't interact for the configured delay, a desktop notification fires. Any keystroke — even just pressing a key without submitting — cancels the timer immediately.
23
+ ```bash
24
+ npm install -g --ignore-scripts @earendil-works/pi-coding-agent
25
+ ```
31
26
 
32
- ## Settings
27
+ After installing Pi, choose one installation command above, then `cd` into your project and run `pi`. Inside the session, `/login` signs you in and `/model` picks a model — the [setup section](https://github.com/danielcherubini/pi-archimedes#setup) covers the first run. `/reload` picks the extension up in a running session.
33
28
 
34
- | Setting | Type | Default | Description |
35
- |---------|------|---------|-------------|
36
- | `notifyOnAgentEnd` | bool | `true` | Notify when agent finishes a task |
37
- | `notifyOnQuestion` | bool | `true` | Notify when a question needs your answer |
38
- | `delayMs` | number | `30000` | Milliseconds to wait before sending notification (default 30 seconds) |
29
+ ## Triggers
30
+
31
+ - **Settled runs** — on Pi's `agent_settled` event: the run has fully settled (no automatic retry, compaction, or queued continuation still to fire), not merely "a turn ended".
32
+ - **Blocking prompts** — on `ui_prompt_start`: any extension prompt is waiting on you (a tabbed ask, a sudo password prompt, an MCP OAuth loader) — direct **or** subagent-relayed, since the event fires in the parent process.
39
33
 
40
- On/off is managed by the suite: toggle via `/plugins` (`archimedes.notify.enabled`, default on).
34
+ The alert fires after a fixed `delayMs` (30 s by default) from the trigger. It is a delay, not an idle timer: nothing measures how long you've been reading. Any input in the terminal cancels pending alerts immediately, a new agent run cancels them, and a prompt that closes without you typing (say, the OAuth loader finishing from the browser) cancels its own timer — so a long-gone question can't ring.
41
35
 
42
- Settings are stored in `~/.pi/agent/settings.json` under the `archimedes.notify` namespace.
36
+ ## Terminal delivery
43
37
 
44
- ## Terminal compatibility
38
+ | Environment | Protocol | Notes |
39
+ |-------------|----------|-------|
40
+ | Windows Terminal | PowerShell toast | title + body |
41
+ | Kitty | OSC 99 | title + body |
42
+ | iTerm2 | OSC 9 | body only |
43
+ | tmux over any of the above | DCS passthrough wrap | alerts break through tmux |
44
+ | other terminals | OSC 777 | generic fallback |
45
45
 
46
- | Terminal | Protocol | Title + Body |
47
- |----------|----------|--------------|
48
- | Kitty | OSC 99 | ✅ |
49
- | iTerm2 | OSC 9 | Body only |
50
- | Windows Terminal | PowerShell toast | ✅ |
51
- | Ghostty | OSC 777 | ✅ |
52
- | WezTerm | OSC 777 | ✅ |
53
- | tmux (any above) | DCS passthrough | ✅ |
46
+ Delivery depends on your terminal understanding one of these protocols; if it understands none, no alert will appear. Both triggers work standalone — the extension alone gets you the same behaviour.
47
+
48
+ ## Settings
54
49
 
55
- ## Integration
50
+ `~/.pi/agent/settings.json`, under `archimedes.notify` (strict JSON):
51
+
52
+ | Setting | Type | Default | Description |
53
+ |---------|------|---------|-------------|
54
+ | `notifyOnAgentEnd` | bool | `true` | Notify when a run has fully settled |
55
+ | `notifyOnQuestion` | bool | `true` | Notify when a blocking prompt needs input |
56
+ | `delayMs` | number | `30000` | Delay after the trigger before the alert fires |
56
57
 
57
- When installed via `pi-archimedes` (the meta package), the notify package is automatically registered and its settings appear in the `/archimedes` settings panel. Standalone installs work independently — any blocking extension UI prompt will trigger the question notification.
58
+ In the suite the settings also appear in `/archimedes` (where the panel has a control), and on/off is managed by the suite: toggle via `/plugins` (`archimedes.notify.enabled`, default on).
58
59
 
59
- ← Back to [pi-archimedes](../../README.md)
60
+ ← [Back to pi-archimedes](https://github.com/danielcherubini/pi-archimedes)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pi-archimedes/notify",
3
- "version": "2.5.1",
3
+ "version": "2.6.2",
4
4
  "type": "module",
5
5
  "keywords": [
6
6
  "pi-package"
@@ -14,15 +14,15 @@
14
14
  ".": "./src/index.ts"
15
15
  },
16
16
  "dependencies": {
17
- "@pi-archimedes/core": "2.5.1"
17
+ "@pi-archimedes/core": "2.6.2"
18
18
  },
19
19
  "peerDependencies": {
20
20
  "@earendil-works/pi-coding-agent": ">=0.84.4",
21
21
  "@earendil-works/pi-tui": ">=0.1.0"
22
22
  },
23
23
  "devDependencies": {
24
- "@earendil-works/pi-coding-agent": "^0.84.4",
25
- "@earendil-works/pi-tui": "^0.84.4",
24
+ "@earendil-works/pi-coding-agent": "^0.85.1",
25
+ "@earendil-works/pi-tui": "^0.85.1",
26
26
  "typescript": "^6.0.0"
27
27
  },
28
28
  "pi": {