pi-attention 0.3.0

package/README.md

@@ -0,0 +1,84 @@
+# pi-attention 🍎
+
+Pi 的 **iTerm2 / Orca 注意力集成扩展**：把 iTerm2 标签页标题显示为**会话第一次 pi 提问**，**回答完成时弹 macOS 系统通知**，并在 **pi 等待你选择时提醒**（权限弹窗 / 计划菜单；iTerm2 原生转义序列与 Orca notification 事件，无需第三方工具）。
+
+- **源码仓库**: [pi-packages](https://github.com/the-ultra-nexus/pi-packages)（GitHub monorepo 负责源码与文档）
+- **npm 包**: `pi-attention`（独立安装、升级和卸载）
+
+## 功能
+
+1. **标题恒定显示提问** — 标题显示本会话最开始的一次提问，跨 reload / resume 稳定，退出时还原。
+2. **回答完成系统通知** — 每次回答完成后，在 macOS 通知中心弹出通知，标题显示 assistant 回复摘要。
+3. **等待用户操作提醒** — 权限弹窗（pi-permission-system）、计划菜单（pi-plan-mode）等阻塞等待你选择时：
+   - **iTerm2**：弹系统通知 + dock 弹跳，终端标题变为「⏸ 等待选择…」；
+   - **Orca**：上报 `notification` 事件，Orca 弹**原生系统通知**（来源为 Orca 应用）——**仅在 Orca 不在前台时弹出**。
+
+## 安装
+
+```bash
+# 全局安装
+pi install npm:pi-attention
+
+# 项目级安装
+pi install -l npm:pi-attention
+
+# 本地开发：在 pi-packages 仓库根目录执行
+pi install ./extensions/pi-attention
+
+# 卸载
+pi remove npm:pi-attention
+```
+
+安装后**重启 pi，或在 pi 内执行 `/reload`** 即可生效。GitHub monorepo 仅作为源码和文档中心，不再通过根目录合集安装本扩展。
+
+## 配置
+
+| 环境变量 | 默认 | 说明 |
+|----------|------|------|
+| `PI_ATTENTION_NOTIFY` | 开 | 设为 `0` 关闭「回答完成通知」 |
+| `PI_ATTENTION_NOTIFY_WAITING` | 开 | 设为 `0` 关闭「等待用户操作」的系统通知 |
+
+### 通知机制（iTerm2 原生，无需第三方工具）
+
+回答完成时，扩展直接向 iTerm2 发送两条**原生转义序列**来触发通知，发送者即 iTerm2：
+
+- `OSC 9 ; <消息>` → 弹系统通知
+- `OSC 1337 ; RequestAttention=once` → dock 图标弹跳一次 + 系统提示音
+
+无需安装 terminal-notifier 或 osascript。仅当不在 iTerm2 终端（如 tmux）时，才回退到 osascript 方式（并用显式提示音）。
+
+### 通知机制（Orca：notification 事件）
+
+Orca pane 下等待用户操作时，扩展经 agent-hook 上报 `notification` 事件（`title` / `body` / `message` / `notification_type`），Orca 主进程走原生系统通知：
+
+- 来源为 **Orca 应用本体**，标题自动带 `pi: ` 前缀；
+- **仅在 Orca 不在前台时弹出**——你正看着窗口时不打扰，切到别的应用时才提醒；
+- 相关调研见 `docs/orca-notification-mechanism.md`（`ui_prompt_*` 为何不被 Orca 消费、`ask_user_question` 白名单等）。
+
+## 标题行为
+
+- 标题**恒定显示本会话最开始的一次提问**（会话里第一条 user 消息），跨 reload / resume 稳定
+- 退出 pi → 标题还原为基础标题 `π · <会话名> · <目录名>`
+
+## 通知
+
+- 回答完成（`agent_settled`，消息已落盘）时触发 iTerm2 原生通知
+- **通知标题显示 assistant 回复摘要**（最后一条回复的前 60 字）
+- 发送者为 iTerm2（OSC 9）+ dock 弹跳 + 系统提示音（`RequestAttention=once`）
+
+## 事件/原理
+
+- `request-title.ts` — 标题 + 回答完成通知
+  - `session_start` — 会话启动/加载/恢复时，设定标题为最开始提问
+  - `agent_settled` — 回答完成（消息已落盘）时触发，发系统通知 + 校正标题
+  - `session_shutdown` — 会话退出时还原标题
+- `waiting-notify.ts` — 等待用户操作提醒（权限弹窗 / 计划菜单 / 任意 `ctx.ui.*` 阻塞提示）
+  - `ui_prompt_start` — 等待开始：标题切「⏸ 等待选择…」；Orca 上报 `notification` 事件 → 原生系统通知（后台才弹）；iTerm2 弹 OSC 通知
+  - `ui_prompt_end` — 等待结束：恢复基础标题
+  - 环境判定：Orca pane（`ORCA_PANE_KEY` / `ORCA_AGENT_HOOK_ENDPOINT`）→ 上报 `notification` 事件；`TERM_PROGRAM === "iTerm.app"` 且非 `PI_WEB_HOSTNAME` → iTerm2 原生通知；否则静默
+
+> 为什么 waiting-notify 不放 Orca 的扩展里：Orca 会定期覆盖它自己分发的扩展（文件头标 `@orca-managed-pi-extension` 的那些），补丁会被冲掉；放本包统一维护。
+
+## License
+
+MIT

package/docs/orca-notification-mechanism.md

@@ -0,0 +1,86 @@
+# Orca 原生通知机制（调研记录）
+
+> 主题：pi 跑在 Orca pane 里时，「等待用户操作」如何获得类似 Orca 原生的提示。
+> 结论先行：Orca 对 hook 事件有三类处理——**状态指示、blocked 等待卡、系统通知（plugin 通知）**；
+> `ui_prompt_*` 不在 Orca 协议内，需要走下面「可行通道」之一。
+> 本文档的代码位置均来自 Orca.app（2026-09 版，macOS 13.7.8）。
+
+---
+
+## 1. Orca 对 hook 上报的总入口
+
+本地 hook 端点：`http://127.0.0.1:<ORCA_AGENT_HOOK_PORT>/hook/<source>`（source 见 `app.asar.unpacked/out/shared/agent-hook-relay.js` 的 `AGENT_HOOK_SOURCES`，含 claude/pi 等）。
+请求头 `X-Orca-Agent-Hook-Token`。pi 侧上报参考实现：`~/.pi/agent/extensions/orca-agent-status.ts`（用户级、`@orca-managed-pi-extension`，会被 Orca 定期覆盖）。
+
+## 2. 三类原生提示
+
+### 2.1 状态指示（agent 生命周期事件）
+- 消费端：`app.asar.unpacked/out/shared/agent-hook-listener/providers/pi-family-events.js`（`normalizePiCompatibleEvent`）
+- pi 的 `agent_start / tool_call / tool_execution_start / tool_execution_end / message_end / agent_end / before_agent_start` → state ∈ {working, done} → Orca 界面内 spinner/完成状态/标题变化
+- **→ 用户实测的「回答完有提示」就是这条**：Orca 原生消费 `agent_end`，无需任何扩展。
+
+### 2.2 blocked（等待用户）状态
+- 判定（pi-family-events.js + agent-question-answered-intent.js）：
+  ```js
+  isPiCompatibleAsk = agentType==='pi' && isAskUserQuestionTool(toolName) &&
+                      (eventName==='tool_call' || eventName==='tool_execution_start')
+  ```
+- `isAskUserQuestionTool`：归一化（去非字母数字、小写）后 === `askuserquestion` || === `requestuserinput`
+  - pi 若用工具名 `ask_user_question`（归一化后 = askuserquestion）会被识别
+  - **`plan_mode_question` / `plan_mode_complete` / 自定义 UI 不在白名单** → Orca 视为普通 working，不显示等待
+- grok 的做法（grok-events.js）：hook `notification` 事件 + `message` 字段含 permission/approval/confirm/needs your/requires your/feedback/clarify/question 等 → state=waiting
+
+### 2.3 plugin 通知（系统通知，来源 = 发送 app）
+- 主进程（app.asar 打包代码）：
+  ```js
+  async dispatchPlugin(e) {
+    let t = `${e.pluginId}: ${e.title}`, n = e.body ?? '', r = !1;
+    try { r = V2().showNotification({ title: t, body: n }) } catch {}
+    return this.dispatch({ type: 'notification', source: 'plugin', title: t, body: n }), { delivered: r }
+  }
+  ```
+  - `showNotification` = Electron `new Notification({title, body}).show()`（打包 `notification:` 段，GNr 函数带 sound/silent 处理）
+- 事件识别：payload 含 `notification_type` / `notificationType` 字段（或 hook 名映射 `notification` → `Notification`，见打包的 hook 事件名映射）
+- **这条通道弹的是真正的 macOS 系统通知，来源是 Orca 应用（或 pluginId 前缀的 app）**——是「像 Orca 原生一样」的提示
+
+## 3. pi 的现状与缺口
+
+| 场景 | Orca 原生表现 | pi-attention 现在的兜底 |
+|------|--------------|------------------------|
+| 回答完成（agent_end） | ✅ Orca 界面状态提示（2.1） | request-title（仅 iTerm2 OSC 生效；Orca 下无动作） |
+| 等待用户（plan/权限弹窗） | ❌ 无（ui_prompt 不在协议内；plan_mode_question 不在白名单） | osascript 系统通知（来源「脚本编辑器」） |
+
+## 4. 让等待获得 Orca 原生提示的可行通道（已定）
+
+**已采用（实验验证通过）——上报 `notification` 事件**：`ui_prompt_start` 时 hook 上报
+
+```json
+{ "hook_event_name": "notification", "message": "Pi 正在等待你的操作", "title": "…", "body": "在 pi 窗口里完成操作", "notification_type": "permission_prompt", "level": "info" }
+```
+
+- ✅ Orca 主进程消费（dispatchPlugin → Electron `new Notification`），弹**原生系统通知**，来源为 Orca 应用；
+- ✅ **仅在 Orca 不在前台时弹出**（前台静默）——正符合「人离开窗口才提醒」的诉求；
+- ✅ 不产生状态快照（provider 层无映射），不污染 last-status.json；
+- ⚠️ `ui_prompt_*` 事件 Orca 不消费（白名单只有 `ask_user_question` / `request_user_input` 的 tool_call），不再上报。
+
+被否 / 备选通道：
+
+1. **伪造 `ask_user_question` 的 tool_call**（副作用大，不推荐）：上报 `tool_call` + `tool_name: "ask_user_question"` → Orca blocked 等待卡；风险：Orca 端可能等用户 submit 才清卡、界面出现伪工具记录。
+2. **osascript 系统通知**（Orca pane 下的旧方案）：来源「脚本编辑器」，前台也弹，已由 notification 事件替换。
+
+## 5. 实验记录（2026-09-06 完成）
+
+- [x] 模拟 POST `notification` 事件（/tmp/sim_notif.py，变体 A：`hook_event_name:'notification'` + message/title/body/notification_type/level）→ **HTTP 204，Orca 弹出原生系统通知**
+- [x] 变体 A 复测：**Orca 在前台时不弹，切走后弹**（前台静默行为确认）
+- [x] 变体 B/C/D（无 message/level、普通工具事件+notification_type、仅 title/body）未再逐一验证——变体 A 已达成目标
+- [x] 未采用 osascript 方案
+- [ ] 变体 B/C/D 的差异行为（如需了解 Orca 通知字段的边界）可后续补充
+- 顺带发现：Orca 的 macOS 通知权限记录（ncprefs flags bit0=0）看似禁止，但 notification 事件的 Electron 通知仍能弹出——以实测为准
+
+## 6. 关键参考文件
+
+- `app.asar.unpacked/out/shared/agent-hook-listener/providers/pi-family-events.js`
+- `app.asar.unpacked/out/shared/agent-question-answered-intent.js`
+- `app.asar.unpacked/out/shared/agent-hook-listener/providers/grok-events.js`、`grok-tool-fields.js`
+- `app.asar.unpacked/out/shared/agent-hook-relay.js`（AGENT_HOOK_SOURCES、转发协议）
+- `~/.pi/agent/extensions/orca-agent-status.ts`（pi 侧上报参考）

package/extensions/request-title.ts

@@ -0,0 +1,145 @@
+/**
+ * pi-attention
+ *
+ * iTerm2 集成扩展。
+ *
+ * 标题: 恒定显示「本会话最开始的一次提问」（会话里第一条 user 消息），
+ *       跨 reload / resume 稳定指向同一句；退出时还原为基础标题。
+ *
+ * 通知: agent_settled（所有消息已落盘，回答真正完成）时，用 iTerm2 原生 OSC
+ *       触发系统通知，通知标题为 assistant 回复摘要；
+ *       PI_ATTENTION_NOTIFY=0 可关闭（默认开启）。
+ */
+
+import { exec } from "node:child_process";
+import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const notifyEnabled = process.env.PI_ATTENTION_NOTIFY !== "0";
+const NOTIFY_DONE = "pi 已完成回答";
+
+function oneLine(s: string): string {
+	return s.replace(/\s+/g, " ").trim();
+}
+
+function clipped(s: string): string {
+	const MAX = 60;
+	return s.length > MAX ? s.slice(0, MAX) + "…" : s;
+}
+
+function cwdName(): string {
+	return path.basename(process.cwd()) || process.cwd();
+}
+
+function baseTitle(pi: ExtensionAPI): string {
+	const session = pi.getSessionName();
+	return session ? `π · ${session} · ${cwdName()}` : `π · ${cwdName()}`;
+}
+
+/** 从一条 message 的 content 中提取纯文本（content 可以是字符串或文本块数组）。 */
+function extractPrompt(content: unknown): string {
+	if (typeof content === "string") return oneLine(content);
+	if (Array.isArray(content)) {
+		return oneLine(
+			content
+				.filter(
+					(c): c is { type: "text"; text: string } =>
+						typeof c === "object" &&
+						c !== null &&
+						(c as { type?: string }).type === "text" &&
+						typeof (c as { text?: unknown }).text === "string",
+				)
+				.map((c) => c.text)
+				.join(" "),
+		);
+	}
+	return "";
+}
+
+type SM = {
+	getEntries(): Array<{ type: string; message?: { role?: string; content?: unknown } }>;
+};
+
+/** 会话里“最开始”的一条 user 提问（第一条）。 */
+function earliestUserPrompt(sm: SM): string {
+	for (const entry of sm.getEntries()) {
+		if (entry.type === "message" && entry.message?.role === "user") {
+			const p = extractPrompt(entry.message.content);
+			if (p) return clipped(p);
+		}
+	}
+	return "";
+}
+
+/** 会话里“最新”的一条 user 提问（最后一条，即当前这次提问）。 */
+function latestUserPrompt(sm: SM): string {
+	let latest = "";
+	for (const entry of sm.getEntries()) {
+		if (entry.type === "message" && entry.message?.role === "user") {
+			const p = extractPrompt(entry.message.content);
+			if (p) latest = clipped(p);
+		}
+	}
+	return latest;
+}
+
+/** 会话里最后一条 assistant 回复的文本摘要。 */
+function latestAssistantText(sm: SM): string {
+	let latest = "";
+	for (const entry of sm.getEntries()) {
+		if (entry.type === "message" && entry.message?.role === "assistant") {
+			const p = extractPrompt(entry.message.content);
+			if (p) latest = clipped(p);
+		}
+	}
+	return latest;
+}
+
+function applyTitle(pi: ExtensionAPI, ctx: { ui: { setTitle(t: string): void } }, sm: SM): void {
+	const earliest = earliestUserPrompt(sm);
+	ctx.ui.setTitle(earliest ? `π · ${earliest} · ${cwdName()}` : baseTitle(pi));
+}
+
+/**
+ * 回答完成时触发 iTerm2 原生系统通知（无需第三方工具）。
+ * 以「assistant 回复摘要」作为通知标题。
+ *   - OSC 9 : 弹系统通知，发送者即 iTerm2
+ *   - OSC 1337 ; RequestAttention=once : dock 图标弹跳一次 + 系统提示音
+ * 非 iTerm2 终端或写入失败时回退 osascript（显式加提示音）。
+ */
+function notifyCompletion(replyText: string) {
+	if (!notifyEnabled || process.platform !== "darwin" || process.env.PI_WEB_HOSTNAME) return;
+	const subject = replyText ? clipped(oneLine(replyText)) : "pi";
+	try {
+		process.stdout.write(`\x1b]9;${subject}\x07`);
+		process.stdout.write("\x1b]1337;RequestAttention=once\x07");
+		return;
+	} catch {
+		// 终端不支持该 OSC 时回退到 osascript（来源会显示为“脚本编辑器”）
+	}
+	const safeSubject = subject.replace(/"/g, '\\"');
+	const script = `display notification "${NOTIFY_DONE}" with title "${safeSubject}" sound name "Glass"`;
+	exec(`osascript -e '${script}'`, () => {});
+}
+
+export default function (pi: ExtensionAPI) {
+	// 标题恒定显示「本会话最开始提问」（会话第一条 user 消息），跨 reload/resume 稳定。
+
+	// 会话启动/加载/恢复时：显示最开始提问（若有历史）
+	pi.on("session_start", async (_event, ctx) => {
+		applyTitle(pi, ctx, ctx.sessionManager);
+	});
+
+	// 回答完成（消息已落盘）：
+	//   1) 通知，标题 = assistant 回复摘要
+	//   2) 校正标题为「最开始提问」
+	pi.on("agent_settled", async (_event, ctx) => {
+		notifyCompletion(latestAssistantText(ctx.sessionManager));
+		applyTitle(pi, ctx, ctx.sessionManager);
+	});
+
+	// 会话退出时把标题还原为基础标题
+	pi.on("session_shutdown", async (_event, ctx) => {
+		ctx.ui.setTitle(baseTitle(pi));
+	});
+}

package/extensions/waiting-notify.ts

@@ -0,0 +1,294 @@
+/**
+ * pi-attention · waiting-notify
+ *
+ * 监听 pi 的「等待用户输入」生命周期事件（ui_prompt_start / ui_prompt_end）。
+ * 这些事件在所有阻塞式用户界面提示弹出时发出：
+ *   - gotgenes/pi-permission-system 的权限「允许/拒绝」弹窗（ctx.ui.custom）
+ *   - narumitw/pi-plan-mode 的计划菜单 / plan_mode_question（ctx.ui.custom / select）
+ *   - 任何 ctx.ui.select / confirm / input / editor / custom 阻塞等用户的操作
+ *
+ * 行为（按宿主环境分流）：
+ *   - Orca pane（ORCA_PANE_KEY / ORCA_AGENT_HOOK_ENDPOINT）：上报 notification
+ *     事件（title/body/message/notification_type），Orca 走原生系统通知——来源为
+ *     Orca 应用，且只在 Orca 不在前台时弹出（前台静默，人离开窗口才提醒）。
+ *     ui_prompt_* 事件 Orca 不消费（白名单只有 ask_user_question /
+ *     request_user_input 的 tool_call），不再上报。
+ *   - iTerm2（TERM_PROGRAM === "iTerm.app" 且非 pi-web）：弹出系统通知（OSC 9，
+ *     发送者即 iTerm2）+ dock 弹跳一次（OSC 1337 RequestAttention=once），并把终端
+ *     标题切换为「⏸ 等待选择…」，选择完成后恢复基础标题。
+ *   - 其它环境（pi-web / 非 iTerm2 终端）：静默，不做通知（标题仍可设置）。
+ *
+ * 为什么放在这里维护：Orca 会定期覆盖它自己分发的扩展
+ * （orca-agent-status.ts、orca-titlebar-spinner.ts 等，文件头标
+ * `@orca-managed-pi-extension`），在那些文件上补丁会被冲掉。本扩展随
+ * pi-attention 包分发，由自己的仓库统一维护。
+ */
+
+import { exec } from "node:child_process";
+import fs from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// ⏸ 开关：PI_ATTENTION_NOTIFY_WAITING=0 关闭「等待用户输入」的系统通知（默认开）
+const waitingNotify = process.env.PI_ATTENTION_NOTIFY_WAITING !== "0";
+
+// 标题最长显示宽度（macOS 通知标题过长会被截断）
+const SUBJECT_MAX = 60;
+
+function oneLine(s: string): string {
+	return s.replace(/\s+/g, " ").trim();
+}
+
+function clipped(s: string): string {
+	return s.length > SUBJECT_MAX ? s.slice(0, SUBJECT_MAX) + "…" : s;
+}
+
+function baseTitle(pi: ExtensionAPI): string {
+	const session = pi.getSessionName();
+	const cwd = process.cwd().split(/[\\/]/).filter(Boolean).at(-1) || process.cwd();
+	return session ? `π · ${session} · ${cwd}` : `π · ${cwd}`;
+}
+
+/** 是否运行在 Orca 托管的 pane 里（其状态走 agent-hook 上报而非终端 OSC）。 */
+function isOrcaPane(): boolean {
+	return !!(process.env.ORCA_PANE_KEY || process.env.ORCA_AGENT_HOOK_ENDPOINT);
+}
+
+/** 是否运行在 iTerm2 终端里（OSC 9 / OSC 1337 只有 iTerm2 原生支持）。 */
+function isITerm2(): boolean {
+	return process.env.TERM_PROGRAM === "iTerm.app";
+}
+
+// ── iTerm2 / 常规终端：通知 + 标题 ──────────────────────────────────────
+
+/**
+ * 「等待用户操作」时触发 iTerm2 原生系统通知 + dock 弹跳。
+ *
+ * 环境判定（与 request-title.ts 同款原则）：
+ *  - TERM_PROGRAM === "iTerm.app"：只在真 iTerm2 里发 OSC（其它终端 OSC 无效）；
+ *  - PI_WEB_HOSTNAME：排除 pi-web（pi-web 在 iTerm2 里跑时 TERM_PROGRAM 仍是
+ *    iTerm.app，单查 TERM_PROGRAM 防不住它，参考 request-title.ts 的 b11c57d 提交）；
+ *  - Orca pane 不在这里处理：事件入口处按 isOrcaPane() 分流到 notifyViaSystem
+ *    （osascript 系统通知——Orca 终端不支持 OSC 9 / OSC 1337，实测会原样回显）。
+ */
+function notifyWaiting(kind: string, title: string | undefined): void {
+	if (
+		!waitingNotify ||
+		process.platform !== "darwin" ||
+		process.env.PI_WEB_HOSTNAME ||
+		!isITerm2()
+	) return;
+	// 标题 = 具体请求内容（与 request-title 的完成通知对称：那头是回复摘要）；
+	// 无具体标题时用默认句。正文 = 固定引导句。
+	const subject = clipped(
+		oneLine(title ? title : "pi 正在等待你的输入"),
+	);
+	const body = "在 pi 窗口里完成操作";
+	try {
+		process.stdout.write(`\x1b]9;${subject}\x07`);
+		process.stdout.write("\x1b]1337;RequestAttention=once\x07");
+		return;
+	} catch {
+		// 终端不支持该 OSC 时回退到 osascript（来源会显示为“脚本编辑器”）
+	}
+	const safeSubject = subject.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, '\\"');
+	const script = `osascript -e 'display notification "${body}" with title "${safeSubject}" sound name "Glass"'`;
+	exec(script, () => {});
+}
+
+/**
+ * Orca pane 环境下的等待提醒：上报 `notification` 事件给 Orca。
+ *
+ * 实测（2026-09，Orca app）：Orca 主进程对 hook 的 notification 事件（含
+ * title/body/message/notification_type）走 dispatchPlugin → Electron 原生系统
+ * 通知，**仅在 Orca 不在前台时弹出**（前台静默，符合「人离开窗口才提醒」的
+ * 预期）；来源为 Orca 应用本体，标题自动带 `${pluginId}: ` 前缀。
+ * `ui_prompt_*` 事件 Orca 不消费（白名单只有 ask_user_question /
+ * request_user_input 的 tool_call），所以这里不再上报它们，只报 notification。
+ */
+function notifyOrcaWaiting(ctx: ExtensionContext, title: string | undefined): void {
+	post(
+		"notification",
+		{
+			message: "Pi 正在等待你的操作",
+			title: clipped(oneLine(title ? title : "pi 正在等待你的输入")),
+			body: "在 pi 窗口里完成操作",
+			notification_type: "permission_prompt",
+			level: "info",
+		},
+		sessionMeta(ctx),
+	);
+}
+
+// ── Orca pane：agent-hook 上报 ──────────────────────────────────────────
+
+// Why: Pi 会 await 扩展处理器。状态上报保持脱离关键路径，且「只保留最新
+// 一条待发」的槽位避免 Orca 接收端在挂起时堆积过期快照。镜像 orca-agent-status。
+const HOOK_POST_TIMEOUT_MS = 1000;
+let activePost = false;
+let pendingPost: { name: string; extra: Record<string, unknown>; meta: Record<string, unknown> } | null = null;
+
+// Why: 每次事件都重读 endpoint 文件很便宜（小文件、很少变化），但 stat+mtime
+// 缓存可避免工具流式执行期间每个事件都重复解析。
+let cachedEndpointKey = "";
+let cachedEndpointValues: Record<string, string> | null = null;
+
+function readEndpointFile(): Record<string, string> | null {
+	const path = process.env.ORCA_AGENT_HOOK_ENDPOINT;
+	if (!path) return null;
+	try {
+		const stat = fs.statSync(path);
+		const cacheKey = stat.mtimeMs + ":" + stat.size + ":" + stat.ino;
+		if (cacheKey === cachedEndpointKey && cachedEndpointValues) return cachedEndpointValues;
+		const contents: string = fs.readFileSync(path, "utf8");
+		const out: Record<string, string> = {};
+		for (const line of contents.split(/\r?\n/)) {
+			const m = line.match(/^(?:set\s+)?([A-Z0-9_]+)=(.*)$/);
+			if (m) out[m[1]] = m[2].replace(/\r$/, "");
+		}
+		cachedEndpointKey = cacheKey;
+		cachedEndpointValues = out;
+		return out;
+	} catch {
+		cachedEndpointKey = "";
+		cachedEndpointValues = null;
+		return null;
+	}
+}
+
+function resolveHookCoords(): Record<string, string | undefined> {
+	const fileEnv = readEndpointFile() || {};
+	return {
+		port: fileEnv.ORCA_AGENT_HOOK_PORT || process.env.ORCA_AGENT_HOOK_PORT,
+		token: fileEnv.ORCA_AGENT_HOOK_TOKEN || process.env.ORCA_AGENT_HOOK_TOKEN,
+		env: fileEnv.ORCA_AGENT_HOOK_ENV || process.env.ORCA_AGENT_HOOK_ENV || "",
+		version: fileEnv.ORCA_AGENT_HOOK_VERSION || process.env.ORCA_AGENT_HOOK_VERSION || "",
+	};
+}
+
+function processName(value: unknown): string {
+	return String(value || "").split(/[\\/]/).pop()?.toLowerCase() || "";
+}
+
+const CONFIGURED_HOOK_PATH = "/hook/pi";
+let cachedOmpRuntime: boolean | null = null;
+
+function isOmpRuntime(): boolean {
+	if (cachedOmpRuntime !== null) return cachedOmpRuntime;
+	if (CONFIGURED_HOOK_PATH === "/hook/omp") {
+		cachedOmpRuntime = true;
+		return true;
+	}
+	const names = [process.title, process.env._, process.argv[1], process.argv[0]].map(processName);
+	cachedOmpRuntime = names.some((n) =>
+		["omp", "omp.js", "omp.sh", "omp.cmd", "omp.exe", "omp.bat"].includes(n),
+	);
+	return cachedOmpRuntime;
+}
+
+function resolveHookPath(ompRuntime: boolean): string {
+	return ompRuntime ? "/hook/omp" : CONFIGURED_HOOK_PATH;
+}
+
+function post(name: string, extra: Record<string, unknown>, meta: Record<string, unknown>): void {
+	pendingPost = { name, extra, meta };
+	drainPosts();
+}
+
+function drainPosts(): void {
+	if (activePost || !pendingPost) return;
+	const next = pendingPost;
+	pendingPost = null;
+	activePost = true;
+	void postOnce(next.name, next.extra, next.meta).catch(() => {}).finally(() => {
+		activePost = false;
+		drainPosts();
+	});
+}
+
+async function postOnce(
+	name: string,
+	extra: Record<string, unknown>,
+	meta: Record<string, unknown>,
+): Promise<void> {
+	const coords = resolveHookCoords();
+	const paneKey = process.env.ORCA_PANE_KEY;
+	if (!coords.port || !coords.token || !paneKey) return;
+	const ompRuntime = isOmpRuntime();
+	const url = `http://127.0.0.1:${coords.port}${resolveHookPath(ompRuntime)}`;
+	const body = JSON.stringify({
+		paneKey,
+		launchToken: process.env.ORCA_AGENT_LAUNCH_TOKEN || "",
+		tabId: process.env.ORCA_TAB_ID || "",
+		worktreeId: process.env.ORCA_WORKTREE_ID || "",
+		env: coords.env,
+		version: coords.version,
+		payload: { hook_event_name: name, ...meta, ...extra },
+	});
+	const controller = typeof AbortController !== "undefined" ? new AbortController() : null;
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	const timeoutPromise = new Promise<never>((_resolve, reject) => {
+		timeout = setTimeout(() => {
+			controller?.abort();
+			reject(new Error("Orca hook delivery timed out"));
+		}, HOOK_POST_TIMEOUT_MS);
+		if (typeof timeout.unref === "function") timeout.unref();
+	});
+	try {
+		await Promise.race([
+			fetch(url, {
+				method: "POST",
+				headers: {
+					"Content-Type": "application/json",
+					"X-Orca-Agent-Hook-Token": coords.token,
+				},
+				body,
+				...(controller ? { signal: controller.signal } : {}),
+			}),
+			timeoutPromise,
+		]);
+	} catch {
+		// Why: 上报失败绝不能反过来弄挂 pi 运行（Orca 重启/下线都属正常）。
+	} finally {
+		if (timeout) clearTimeout(timeout);
+	}
+}
+
+/** 当前会话的 session_id / session_file，与 orca-agent-status 同构。 */
+function sessionMeta(ctx: ExtensionContext): Record<string, unknown> {
+	const sm = ctx?.sessionManager;
+	const id = sm?.getSessionId?.();
+	const file = sm?.getSessionFile?.();
+	return {
+		...(typeof id === "string" && id ? { session_id: id } : {}),
+		...(typeof file === "string" && file ? { session_file: file } : {}),
+	};
+}
+
+// ── 注册 ────────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI): void {
+	// Why: 子 agent 进程会继承 lead 的 pane env；只允许第一个（最外层）进程
+	// 处理等待提醒，避免子进程重复通知/重复上报。与 orca-agent-status 同款 PID 门禁。
+	const ownerPid = process.env.ORCA_PI_STATUS_OWNED;
+	const selfPid = String(process.pid);
+	if (ownerPid && ownerPid !== selfPid) return;
+	process.env.ORCA_PI_STATUS_OWNED = selfPid;
+
+	// 等待用户输入开始：Orca 走系统通知兜底 + hook 上报；iTerm2 走 OSC 通知。
+	pi.on("ui_prompt_start", (event, ctx) => {
+		const title = event.title;
+		if (isOrcaPane()) {
+			// Orca 原生：notification 事件 → 系统通知（后台才弹，前台静默）
+			notifyOrcaWaiting(ctx, title);
+		} else {
+			notifyWaiting(event.kind, title);
+		}
+		ctx.ui?.setTitle(`⏸ 等待选择… · ${baseTitle(pi)}`);
+	});
+
+	// 等待结束：恢复基础标题
+	// （request-title.ts 会在 agent_settled / session_start 再校正为「最早提问」）。
+	pi.on("ui_prompt_end", (event, ctx) => {
+		ctx.ui?.setTitle(baseTitle(pi));
+	});
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "pi-attention",
+  "version": "0.3.0",
+  "description": "Pi extension for iTerm2/Orca attention: title shows the first user request, notify on completion, and alert when pi is waiting for your selection (permission dialogs, plan-mode menus).",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["pi-package", "iterm2", "attention", "title", "notification", "macos"],
+  "files": ["README.md", "docs", "extensions"],
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}