monotonic-pi-extensions/plans/pi-notifications-version-0.md

# Plan: pi-notifications v0 — Desktop Notifications for Agent Events

## Goal

Make the `pi-notifications` extension reliably show macOS Notification Center alerts when the agent finishes a turn, so the user gets alerted without needing to watch the screen.

## Current State

- Extension exists at `packages/pi-notifications/src/index.ts` (monorepo) and `~/.pi/agent/extensions/pi-notifications.ts` (auto-discovery)
- Extension loads correctly (appears in `/reload` extension list)
- `console.log` from extensions is NOT visible in `/reload` output
- `osascript` works when run directly in bash, but notification doesn't appear when called from the extension
- The `session_start` handler fires on reload, `agent_end` fires when prompts complete

## Debugging Strategy (split into two orthogonal problems)

### Problem A: "Does the trigger fire?" — visible debug signal

`console.log` from extensions is invisible in pi's TUI output. To debug the trigger logic in a fast loop, add a **debug mode** (`PI_NOTIFICATION_DEBUG=true`) that emits a visible signal via `ctx.ui.steer()` (or similar) right before calling `notify()`. This surfaces in the chat/TUI so you can verify the handler fires without needing actual desktop notifications.

### Problem B: "Does `osascript` actually deliver?" — isolated tester

Create a standalone script (`test-notify.ts`) that you run from bash independently of the agent loop. This verifies `osascript` works in the extension's import context, decoupled from event handlers.

### 1. Verify `osascript` works in extension context

The extension uses `execSync` from `node:child_process`. Test that it works inside the extension:

```typescript
// In the extension, add this to session_start handler:
try {
  const output = execSync('osascript -e "display notification \\"test\\" with title \\"test\\""').toString();
  console.log("[pi-notifications] osascript output:", output);
} catch (e: any) {
  console.log("[pi-notifications] osascript error:", e.message, e.stderr?.toString());
}
```

If `execSync` fails silently, try:
- Using `{ stdio: ["pipe", "pipe", "pipe"] }` to capture stderr
- Checking if `node:child_process` is available in the extension sandbox

### 2. Check macOS notification settings

Notifications may be delivered but not shown as banners:
- **System Settings → Notifications → Ghostty → Notification Style** — must be "Banners" or "Alerts", not "None" (osascript fires from the Ghostty process, so macOS attributes notifications to Ghostty, not "pi")
- **System Settings → Focus → [active focus] → Apps** — ensure "Ghostty" is not excluded
- **System Settings → Notifications → Show Notifications on Lock Screen** — enable if needed

**Known symptom:** Notifications appear in Notification Center when pulled down, but never pop up as banners. This is a macOS style setting, not a code issue.

### 3. Ghostty suppresses banners when focused

Ghostty intentionally silences banner notifications (no pop-up, no sound) when the Ghostty window is **active/focused**. The notification is still delivered to Notification Center. Banners only appear when Ghostty is **not** the active window.

**Workarounds:**
- **System Settings → Notifications → Ghostty → Alert Style → "Persistent"** — macOS shows these as banners regardless of Ghostty's silencing
- **Switch to another app** (e.g. leave your browser open) when you want to see the banner

### 3. Try alternative notification methods

If `osascript` doesn't work from the extension, try:
- `notify-send` (Linux-only, not relevant for macOS)
- A custom TUI widget that shows a persistent banner
- Using `ctx.ui.notify()` (but this only shows in pi's TUI, not system notification)

### 4. Verify event handlers fire

Add a `session_start` handler that definitely fires:

```typescript
pi.on("session_start", async (_event, ctx) => {
  console.log("[pi-notifications] session_start fired");
  ctx.ui.notify("pi-notifications active", "info");  // Shows in TUI
});
```

If `ctx.ui.notify()` works but `osascript` doesn't, the issue is macOS notification permissions, not the extension.

## Implementation Plan

### Step 0A: Add debug mode with visible signal (PI_NOTIFICATION_DEBUG)

Add a `PI_NOTIFICATION_DEBUG=true` env var. When enabled, the extension calls `ctx.ui.steer()` (or a visible TUI signal) right before each notification, so you see "notification triggered" in the chat output during the agent loop. This lets you verify trigger logic without needing actual desktop notifications.

- In `agent_end` handler: if `PI_NOTIFICATION_DEBUG=true`, call `ctx.ui.steer("[pi-notifications] notification triggered")` before `notify()`
- In `session_start` handler: same pattern
- This is purely for debugging — no desktop notification shown when debug is on (or both are shown)

### Step 0B: Create isolated notification tester

Create `packages/pi-notifications/src/test-notify.ts` — a standalone script runnable via `npx jiti` that fires a test notification. Run it from bash to verify `osascript` works in the extension's context, completely separate from the agent loop.

### Step 1: Fix notification delivery (priority)

Once the root cause is identified:

**If `osascript` works but notification is suppressed:**
- Add a `PI_NOTIFICATION_SOUND` env var (already in design)
- Add `PI_NOTIFICATIONS_ENABLED` toggle (already in design)
- Consider adding a "first-run" notification that asks user to enable notifications

**If `osascript` doesn't work from extension:**
- Fall back to `ctx.ui.notify()` which shows in pi's TUI
- Or use a different approach (e.g., write to a file that a separate process monitors)

### Step 2: Add turn-limit notification

In `packages/pi-turn-limit/src/turn-limit.ts`, add notification when the limit is reached:

```typescript
// In the turn-limit extension, when the limit fires:
if (shouldNotify) {
  execSync('osascript -e \'display notification "Turn limit reached" with title "pi" subtitle "Turns: ' + turnCount + '/' + maxTurns + '"\'');
}
```

Configuration via env var:
- `PI_NOTIFICATION_TURN_LIMIT` — default `true`, set to `false` to disable

### Step 3: Add sound option

Already designed in the extension:
- `PI_NOTIFICATION_SOUND` env var (default: `default`)
- macOS sounds: `Bottle`, `Ping`, `Pop`, `Submarine`, `Sosumi`, `Tink`
- Set to `""` for silent

### Step 4: Update README

Document the extension with:
- What it does
- Configuration options
- How to enable macOS notifications
- Troubleshooting tips

## Files to Modify

| File | Action |
|------|--------|
| `~/.pi/agent/extensions/pi-notifications.ts` | Debug and fix notification delivery |
| `packages/pi-notifications/src/index.ts` | Sync fixes from auto-discovery version |
| `packages/pi-turn-limit/src/turn-limit.ts` | Add turn-limit notification |
| `packages/pi-notifications/README.md` | Update with notification docs |

## Success Criteria

1. ✅ Extension loads and appears in `/reload` output
2. ✅ macOS Notification Center shows "pi-notifications active" on reload
3. ✅ macOS Notification Center shows "Agent finished — N turns" when agent completes a prompt
4. ✅ Turn-limit notification shows when turn limit is exceeded
5. ✅ `PI_NOTIFICATIONS_ENABLED=false` disables all notifications
6. ✅ README documents all configuration options
7. ✅ `PI_NOTIFICATION_DEBUG=true` shows visible signal in TUI when handlers fire
8. ✅ `test-notify.ts` fires a notification when run standalone