pi-notifications 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# pi-notifications
+
+Configurable external notifications for the [Pi coding agent](https://pi.dev).
+
+[中文文档](./README.zh-CN.md)
+
+## Features
+
+- Sends a system notification before `ask_user_question` or the legacy `ask_user` tool waits for input.
+- Sends a completion notification after each Pi agent run, including whether a tool reported an error and the number of completed turns.
+- Runs the adapter with Node's argv API, never through a shell, so notification text is not re-parsed as command syntax.
+- Detects the configured command at runtime. A missing command or the first failed invocation produces one in-session warning and then disables external notifications for that runtime.
+- Notification failures never block Pi's agent lifecycle or tool execution.
+- All runtime messages are localized through `pi-extensions-i18n`.
+
+## Install
+
+```bash
+pi install npm:pi-notifications
+```
+
+Then reload Pi:
+
+```text
+/reload
+```
+
+Install the shared i18n package automatically through this package's dependency. The default adapter expects `terminal-notifier` to be available in `PATH`.
+
+## Configuration
+
+The optional configuration file is:
+
+```text
+<pi-agent-dir>/extensions/pi-notifications/config.json
+```
+
+`<pi-agent-dir>` is Pi's configured agent directory (normally `~/.pi/agent`). Start from [`config.example.json`](./config.example.json). Configuration fields are:
+
+- `enabled`: set to `false` to disable external notifications.
+- `adapter.command`: executable name or path.
+- `adapter.args`: argv entries. `{title}`, `{subtitle}`, and `{message}` are replaced in each entry.
+- `timeoutMs`: maximum time for one adapter invocation.
+
+For example, a custom adapter can use an executable directly:
+
+```json
+{
+  "enabled": true,
+  "adapter": {
+    "command": "notify-send",
+    "args": ["{title}", "{message}"]
+  },
+  "timeoutMs": 3000
+}
+```
+
+The configuration file is read when the extension loads. Use `/config:notifications` to open the normal TUI settings menu, or use `reset` to restore defaults. Run `/reload` after saving. A missing file uses the default `terminal-notifier` configuration. A malformed file is reported in Pi and uses the default configuration.
+
+## Default adapter
+
+The default argv is equivalent to:
+
+```text
+terminal-notifier -title <title> -subtitle <subtitle> -message <message> -sound default -timeout 5
+```
+
+Install it using the package manager appropriate for your operating system, or configure another notification executable. The package does not assume a specific operating system daemon.
+
+## Localization
+
+Runtime messages are provided in `zh-CN` and `en-US` through `pi-extensions-i18n`. Set the shared language with `/config:language` or `PI_EXTENSIONS_LOCALE`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,76 @@
+# pi-notifications
+
+面向 [Pi coding agent](https://pi.dev) 的可配置外部通知扩展。
+
+[English](./README.md)
+
+## 功能
+
+- 在 `ask_user_question` 或旧版 `ask_user` 工具等待输入前发送系统通知。
+- 每次 Pi agent 运行结束后发送完成通知，包含工具是否报错和已完成的 turn 数。
+- 使用 Node 的 argv API 执行 adapter，不经过 shell，通知文本不会被重新解析为命令语法。
+- 运行时探测配置的命令。命令缺失或首次执行失败时，在当前会话明确提示一次，随后停用本次运行的外部通知。
+- 通知失败不会阻塞 Pi 的 agent 生命周期或工具执行。
+- 所有运行时文案均通过 `pi-extensions-i18n` 国际化。
+
+## 安装
+
+```bash
+pi install npm:pi-notifications
+```
+
+然后重新加载 Pi：
+
+```text
+/reload
+```
+
+本包会自动安装共享的 i18n 依赖。默认 adapter 要求 `terminal-notifier` 位于 `PATH` 中。
+
+## 配置
+
+可选配置文件路径：
+
+```text
+<Pi agent 目录>/extensions/pi-notifications/config.json
+```
+
+`<Pi agent 目录>` 是 Pi 当前配置的 agent 目录（通常为 `~/.pi/agent`）。可以从 [`config.example.json`](./config.example.json) 开始。配置字段如下：
+
+- `enabled`：设为 `false` 可关闭外部通知。
+- `adapter.command`：可执行文件名或路径。
+- `adapter.args`：argv 参数数组；每个参数中的 `{title}`、`{subtitle}`、`{message}` 会被替换。
+- `timeoutMs`：单次 adapter 执行的最长时间。
+
+例如，直接使用另一个通知命令：
+
+```json
+{
+  "enabled": true,
+  "adapter": {
+    "command": "notify-send",
+    "args": ["{title}", "{message}"]
+  },
+  "timeoutMs": 3000
+}
+```
+
+配置在扩展加载时读取。使用 `/config:notifications` 打开常规 TUI 配置菜单，输入 `reset` 恢复默认值；保存后执行 `/reload`。配置文件不存在时使用默认的 `terminal-notifier` 配置；配置格式损坏时会在 Pi 中明确提示并使用默认配置。
+
+## 默认 adapter
+
+默认 argv 等价于：
+
+```text
+terminal-notifier -title <title> -subtitle <subtitle> -message <message> -sound default -timeout 5
+```
+
+请使用适合当前操作系统的包管理器安装它，或配置其他通知可执行文件。本包不假定某个特定操作系统 daemon 存在。
+
+## 国际化
+
+运行时文案通过 `pi-extensions-i18n` 提供 `zh-CN` 和 `en-US`。使用 `/config:language` 或 `PI_EXTENSIONS_LOCALE` 设置共享语言。
+
+## 许可证
+
+MIT

package/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: configure-pi-notifications
+description: 配置与排查 pi-notifications 的外部通知命令、argv 参数、超时和一次性失败提示。Use when configuring or diagnosing Pi external notifications.
+---
+
+# 配置 pi-notifications
+
+## 配置文件
+
+读取实际 Pi agent 目录下的 `extensions/pi-notifications/config.json`。不存在时使用内置默认配置；不要猜测未列出的字段。可以从包内 `config.example.json` 开始。
+
+配置字段：
+
+- `enabled`：布尔值，默认 `true`。
+- `adapter.command`：通知可执行文件名或路径，默认 `terminal-notifier`。
+- `adapter.args`：argv 字符串数组；支持 `{title}`、`{subtitle}`、`{message}` 占位符。
+- `timeoutMs`：正整数，默认 `3000`。
+
+修改配置后执行 `/reload`。配置文件损坏会明确提示，并使用默认配置继续启动。
+
+使用 `/config:notifications` 在 TUI 中修改完整通知配置，输入 `reset` 恢复默认值。保存后执行 `/reload`。
+
+Use `/config:notifications` to edit the complete notification configuration in the TUI, use `reset` for defaults, and run `/reload` after saving.
+
+## 运行行为
+
+- `ask_user_question` 和 `ask_user` 在真正等待输入前发送通知。
+- `agent_end` 发送完成通知，并根据 tool result 是否报错选择完成或错误标题；消息包含 turn 数和耗时。
+- 命令通过 argv 执行，不经过 shell；不要把整条 shell 命令写入 `adapter.args`。
+- 扩展加载时不依赖外部命令存在；第一次发送通知时探测命令。
+- 命令缺失或第一次执行失败只提示一次，并停用当前运行的外部通知；Pi 任务继续执行，不要重试或阻塞。
+- 运行时文案语言由 `pi-extensions-i18n` 控制。
+
+## 排查
+
+1. 检查配置文件的 JSON、`enabled`、命令和 argv 参数类型。
+2. 在当前 Pi 进程的 `PATH` 中确认配置的命令可执行。
+3. 如果看到一次“命令不可用”或“执行失败”提示，先修复命令或配置，再执行 `/reload`。
+4. 不要读取凭据、Pi settings 或私有服务来排查通知 adapter。
+
+## 验证
+
+- 定向测试：`npm test --workspace pi-notifications`。
+- 类型检查：`npm run typecheck --workspace pi-notifications`。
+- 手动 TUI 验证：在 agent 触发一次 `ask_user_question`，再完成一次普通任务；确认系统通知出现且 Pi 不被阻塞。
+- 缺少通知命令、命令退出失败和超时属于预期降级场景；确认每种场景只出现一次明确提示。

package/config.example.json

@@ -0,0 +1,19 @@
+{
+  "enabled": true,
+  "adapter": {
+    "command": "terminal-notifier",
+    "args": [
+      "-title",
+      "{title}",
+      "-subtitle",
+      "{subtitle}",
+      "-message",
+      "{message}",
+      "-sound",
+      "default",
+      "-timeout",
+      "5"
+    ]
+  },
+  "timeoutMs": 3000
+}

package/index.ts

@@ -0,0 +1,4 @@
+export { default } from "./src/index.ts";
+export * from "./src/index.ts";
+export * from "./src/adapter.ts";
+export * from "./src/config.ts";

package/locales/index.json

@@ -0,0 +1,122 @@
+{
+  "inputTitle": {
+    "zh-CN": "Pi · {project} 💬",
+    "en-US": "Pi · {project} 💬"
+  },
+  "inputNeeded": {
+    "zh-CN": "需要你的输入",
+    "en-US": "Input required"
+  },
+  "multipleQuestions": {
+    "zh-CN": "{prefix}{question} …等 {count} 个问题",
+    "en-US": "{prefix}{question} …and {count} more question(s)"
+  },
+  "taskTitle": {
+    "zh-CN": "Pi · {project}",
+    "en-US": "Pi · {project}"
+  },
+  "taskError": {
+    "zh-CN": "⚠️ 执行完成（有错误）",
+    "en-US": "⚠️ Finished with errors"
+  },
+  "taskDone": {
+    "zh-CN": "✅ 执行完成",
+    "en-US": "✅ Finished"
+  },
+  "stepCount": {
+    "zh-CN": "共 {count} 步，耗时 {seconds}s",
+    "en-US": "{count} steps, took {seconds}s"
+  },
+  "elapsed": {
+    "zh-CN": "耗时 {seconds}s",
+    "en-US": "Took {seconds}s"
+  },
+  "adapterMissing": {
+    "zh-CN": "通知 adapter 命令不可用：{command}。本次会话已停用系统通知。",
+    "en-US": "Notification adapter command is unavailable: {command}. System notifications are disabled for this session."
+  },
+  "sendFailed": {
+    "zh-CN": "通知 adapter 执行失败：{command}（{reason}）。本次会话已停用系统通知。",
+    "en-US": "Notification adapter failed: {command} ({reason}). System notifications are disabled for this session."
+  },
+  "configInvalid": {
+    "zh-CN": "通知配置读取失败：{path}（{reason}）。已使用默认配置。",
+    "en-US": "Failed to read notification config: {path} ({reason}). Default configuration is being used."
+  },
+  "configCommandDescription": {
+    "zh-CN": "配置系统通知",
+    "en-US": "Configure system notifications"
+  },
+  "configCommandUsage": {
+    "zh-CN": "用法：/config:notifications（打开配置菜单）或 /config:notifications reset（恢复默认值）",
+    "en-US": "Usage: /config:notifications (open settings) or /config:notifications reset (restore defaults)"
+  },
+  "configMenuTitle": {
+    "zh-CN": "通知配置",
+    "en-US": "Notification settings"
+  },
+  "configEnabled": {
+    "zh-CN": "启用通知：{value}",
+    "en-US": "Notifications enabled: {value}"
+  },
+  "configCommand": {
+    "zh-CN": "通知命令：{value}",
+    "en-US": "Notification command: {value}"
+  },
+  "configArguments": {
+    "zh-CN": "命令参数：{value}",
+    "en-US": "Command arguments: {value}"
+  },
+  "configTimeout": {
+    "zh-CN": "超时：{value} ms",
+    "en-US": "Timeout: {value} ms"
+  },
+  "configOn": {
+    "zh-CN": "开",
+    "en-US": "on"
+  },
+  "configOff": {
+    "zh-CN": "关",
+    "en-US": "off"
+  },
+  "configDone": {
+    "zh-CN": "完成",
+    "en-US": "Done"
+  },
+  "configCommandInput": {
+    "zh-CN": "通知命令路径",
+    "en-US": "Notification command path"
+  },
+  "configArgumentsInput": {
+    "zh-CN": "命令参数（多个参数用逗号分隔）",
+    "en-US": "Command arguments (separate arguments with commas)"
+  },
+  "configTimeoutInput": {
+    "zh-CN": "超时毫秒数（正整数）",
+    "en-US": "Timeout in milliseconds (positive integer)"
+  },
+  "configPresetValue": {
+    "zh-CN": "常用值：{value}",
+    "en-US": "Common value: {value}"
+  },
+  "configCustom": {
+    "zh-CN": "自定义…",
+    "en-US": "Custom…"
+  },
+  "configCancel": {
+    "zh-CN": "取消",
+    "en-US": "Cancel"
+  },
+  "configCommandInteractiveOnly": {
+    "zh-CN": "通知配置需要在 TUI 中修改；请在交互式 Pi 会话中执行命令。",
+    "en-US": "Notification configuration requires the TUI; run this command in an interactive Pi session."
+  },
+  "configCommandSaved": {
+    "zh-CN": "通知配置已保存：{path}。请执行 /reload 使配置生效。",
+    "en-US": "Notification configuration saved to {path}. Run /reload to apply it."
+  },
+  "configCommandInvalid": {
+    "zh-CN": "通知配置无效：{error}",
+    "en-US": "Invalid notification configuration: {error}"
+  }
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "pi-notifications",
+  "version": "0.1.0",
+  "description": "Configurable external notifications for Pi agent lifecycle events",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "locales",
+    "config.example.json",
+    "README.md",
+    "README.zh-CN.md",
+    "SKILL.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit --pretty false",
+    "build": "npm run typecheck",
+    "check": "npm run typecheck && npm test && npm pack --dry-run --json > /dev/null"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts",
+      "../pi-extensions-i18n/index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
+    ]
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "author": "maplezzk",
+  "homepage": "https://github.com/maplezzk/pi-extensions/tree/main/packages/pi-notifications",
+  "bugs": {
+    "url": "https://github.com/maplezzk/pi-extensions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maplezzk/pi-extensions.git",
+    "directory": "packages/pi-notifications"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "coding-agent",
+    "notifications",
+    "terminal-notifier"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0 <0.81.0"
+  },
+  "dependencies": {
+    "pi-extensions-i18n": "^0.4.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@types/node": "24.12.4",
+    "tsx": "4.23.1",
+    "typescript": "5.9.3"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,182 @@
+import { accessSync, constants } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { spawn } from "node:child_process";
+
+export interface NotificationPayload {
+  title: string;
+  subtitle: string;
+  message: string;
+}
+
+export interface NotificationAdapterConfig {
+  command: string;
+  args: string[];
+}
+
+export type NotificationFailureKind = "missing" | "failed";
+
+export interface NotificationFailure {
+  kind: NotificationFailureKind;
+  command: string;
+  reason: string;
+}
+
+export type CommandAvailability = (command: string) => boolean;
+export type RunArgvCommand = (command: string, args: string[], timeoutMs: number) => Promise<void>;
+
+export interface NotificationAdapterOptions {
+  isCommandAvailable?: CommandAvailability;
+  run?: RunArgvCommand;
+}
+
+export interface NotificationAdapter {
+  send(payload: NotificationPayload): Promise<void>;
+}
+
+const WINDOWS_DEFAULT_EXTENSIONS = [".COM", ".EXE", ".BAT", ".CMD"];
+
+/** 把通知内容按 argv 参数模板展开，不经过 shell。 */
+export function renderNotificationArgs(
+  args: readonly string[],
+  payload: NotificationPayload,
+): string[] {
+  const values: Record<string, string> = {
+    title: payload.title,
+    subtitle: payload.subtitle,
+    message: payload.message,
+  };
+  return args.map((arg) => arg.replace(/\{(title|subtitle|message)\}/g, (_, key: string) => values[key]));
+}
+
+/** 检查命令是否能在当前运行时找到，避免调用 command -v 或其他 shell。 */
+export function isCommandAvailable(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed) return false;
+
+  if (isAbsolute(trimmed) || trimmed.includes("/") || trimmed.includes("\\")) {
+    return canExecute(trimmed);
+  }
+
+  const pathValue = process.env.PATH ?? "";
+  const candidates = pathValue.split(process.platform === "win32" ? ";" : ":");
+  const extensions = process.platform === "win32" ? windowsExtensions(trimmed) : [""];
+  return candidates.some((directory) => {
+    if (!directory) return false;
+    return extensions.some((extension) => canExecute(resolve(directory, `${trimmed}${extension}`)));
+  });
+}
+
+function windowsExtensions(command: string): string[] {
+  if (command.includes(".")) return [""];
+  const configured = process.env.PATHEXT
+    ?.split(";")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  return configured && configured.length > 0 ? configured : WINDOWS_DEFAULT_EXTENSIONS;
+}
+
+function canExecute(path: string): boolean {
+  try {
+    accessSync(path, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 使用 Node spawn 的 argv 形式执行外部通知命令。 */
+export function runArgvCommand(
+  command: string,
+  args: string[],
+  timeoutMs: number,
+): Promise<void> {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+      if (error) rejectPromise(error);
+      else resolvePromise();
+    };
+
+    let child;
+    try {
+      child = spawn(command, args, {
+        shell: false,
+        stdio: "ignore",
+        windowsHide: true,
+      });
+    } catch (error) {
+      finish(toError(error));
+      return;
+    }
+
+    timeoutHandle = setTimeout(() => {
+      child.kill();
+      finish(new Error(`command timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    child.once("error", (error) => finish(toError(error)));
+    child.once("close", (code, signal) => {
+      if (code === 0) {
+        finish();
+        return;
+      }
+      const status = signal ? `signal ${signal}` : `exit code ${String(code)}`;
+      finish(new Error(`command failed with ${status}`));
+    });
+  });
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * 创建一次性失效的 argv 通知 adapter。
+ * 第一次缺少命令或执行失败后停止后续尝试，由调用方负责展示一次提示。
+ */
+export function createArgvNotificationAdapter(
+  config: NotificationAdapterConfig,
+  timeoutMs: number,
+  options: NotificationAdapterOptions = {},
+): NotificationAdapter {
+  const checkCommand = options.isCommandAvailable ?? isCommandAvailable;
+  const run = options.run ?? runArgvCommand;
+  let disabled = false;
+  let commandChecked = false;
+  let commandAvailable = false;
+
+  return {
+    async send(payload) {
+      if (disabled) return;
+
+      if (!commandChecked) {
+        commandChecked = true;
+        commandAvailable = checkCommand(config.command);
+      }
+      if (!commandAvailable) {
+        disabled = true;
+        throw <NotificationFailure>{
+          kind: "missing",
+          command: config.command,
+          reason: "command not found in PATH",
+        };
+      }
+
+      try {
+        await run(config.command, renderNotificationArgs(config.args, payload), timeoutMs);
+      } catch (error) {
+        disabled = true;
+        throw <NotificationFailure>{
+          kind: "failed",
+          command: config.command,
+          reason: error instanceof Error ? error.message : String(error),
+        };
+      }
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,147 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { NotificationAdapterConfig } from "./adapter.ts";
+
+export interface NotificationConfig {
+  enabled: boolean;
+  adapter: NotificationAdapterConfig;
+  timeoutMs: number;
+}
+
+export interface ConfigDiagnostic {
+  path: string;
+  reason: string;
+}
+
+export interface LoadedNotificationConfig {
+  config: NotificationConfig;
+  diagnostic?: ConfigDiagnostic;
+}
+
+export const DEFAULT_NOTIFICATION_CONFIG: NotificationConfig = {
+  enabled: true,
+  adapter: {
+    command: "terminal-notifier",
+    args: [
+      "-title",
+      "{title}",
+      "-subtitle",
+      "{subtitle}",
+      "-message",
+      "{message}",
+      "-sound",
+      "default",
+      "-timeout",
+      "5",
+    ],
+  },
+  timeoutMs: 3000,
+};
+
+const CONFIG_FILE_NAME = "config.json";
+const CONFIG_DIRECTORY_NAME = "pi-notifications";
+
+/** 返回当前 Pi agent 目录下的通知配置路径。 */
+export function configPath(): string {
+  return join(getAgentDir(), "extensions", CONFIG_DIRECTORY_NAME, CONFIG_FILE_NAME);
+}
+
+/** 将经过校验的通知配置写入配置文件。 */
+export function saveConfig(config: NotificationConfig, path = configPath()): string {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return path;
+}
+
+/** 读取通知配置；文件缺失时使用默认配置。 */
+export function loadConfig(): NotificationConfig {
+  return loadConfigWithDiagnostics().config;
+}
+
+/** 读取通知配置，并保留损坏配置的诊断信息供 UI 一次提示。 */
+export function loadConfigWithDiagnostics(): LoadedNotificationConfig {
+  const path = configPath();
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) return { config: cloneDefaultConfig() };
+    return {
+      config: cloneDefaultConfig(),
+      diagnostic: { path, reason: errorMessage(error) },
+    };
+  }
+
+  try {
+    return { config: parseConfig(JSON.parse(raw)) };
+  } catch (error) {
+    return {
+      config: cloneDefaultConfig(),
+      diagnostic: { path, reason: errorMessage(error) },
+    };
+  }
+}
+
+/** 解析并校验通知配置，供文件加载和配置命令共同使用。 */
+export function parseConfig(value: unknown): NotificationConfig {
+  if (!isRecord(value)) throw new Error("configuration must be a JSON object");
+
+  const enabled = value.enabled === undefined ? true : value.enabled;
+  if (typeof enabled !== "boolean") throw new Error("enabled must be a boolean");
+
+  const adapterValue = value.adapter === undefined
+    ? DEFAULT_NOTIFICATION_CONFIG.adapter
+    : value.adapter;
+  if (!isRecord(adapterValue)) throw new Error("adapter must be an object");
+
+  const command = adapterValue.command;
+  if (typeof command !== "string" || command.trim() === "") {
+    throw new Error("adapter.command must be a non-empty string");
+  }
+
+  const args = adapterValue.args;
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string")) {
+    throw new Error("adapter.args must be an array of strings");
+  }
+
+  const timeoutMs = value.timeoutMs === undefined
+    ? DEFAULT_NOTIFICATION_CONFIG.timeoutMs
+    : value.timeoutMs;
+  if (
+    typeof timeoutMs !== "number" ||
+    !Number.isInteger(timeoutMs) ||
+    timeoutMs <= 0
+  ) {
+    throw new Error("timeoutMs must be a positive integer");
+  }
+
+  return {
+    enabled,
+    adapter: { command: command.trim(), args: [...args] },
+    timeoutMs,
+  };
+}
+
+function cloneDefaultConfig(): NotificationConfig {
+  return {
+    enabled: DEFAULT_NOTIFICATION_CONFIG.enabled,
+    adapter: {
+      command: DEFAULT_NOTIFICATION_CONFIG.adapter.command,
+      args: [...DEFAULT_NOTIFICATION_CONFIG.adapter.args],
+    },
+    timeoutMs: DEFAULT_NOTIFICATION_CONFIG.timeoutMs,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException).code === "ENOENT";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/i18n.ts

@@ -0,0 +1,3 @@
+import { createTranslator, loadCatalog } from "pi-extensions-i18n";
+
+export const i18n = createTranslator(loadCatalog(new URL("../locales/index.json", import.meta.url)));

package/src/index.ts

@@ -0,0 +1,386 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import {
+  createArgvNotificationAdapter,
+  type NotificationAdapter,
+  type NotificationFailure,
+  type NotificationPayload,
+} from "./adapter.ts";
+import { loadConfigWithDiagnostics, parseConfig, saveConfig, type NotificationConfig } from "./config.ts";
+import { i18n } from "./i18n.ts";
+
+export type { NotificationConfig } from "./config.ts";
+export type {
+  CommandAvailability,
+  NotificationAdapter,
+  NotificationAdapterConfig,
+  NotificationAdapterOptions,
+  NotificationFailure,
+  NotificationFailureKind,
+  NotificationPayload,
+  RunArgvCommand,
+} from "./adapter.ts";
+export {
+  createArgvNotificationAdapter,
+  isCommandAvailable,
+  renderNotificationArgs,
+  runArgvCommand,
+} from "./adapter.ts";
+export { configPath, loadConfig, loadConfigWithDiagnostics, parseConfig, saveConfig } from "./config.ts";
+
+interface Notice {
+  level: "warning";
+  message: string;
+}
+
+interface NotificationRuntime {
+  config: NotificationConfig;
+  adapter: NotificationAdapter | null;
+  failureReported: boolean;
+  context?: ExtensionContext;
+}
+
+const CONFIG_COMMAND_ALIASES = ["config:notifications", "notifications-config", "pi-notifications-config"] as const;
+const CONFIG_RESET_COMMAND = "reset";
+const CONFIG_OPTION = { enabled: 0, command: 1, args: 2, timeout: 3 } as const;
+const CONFIG_ARG_SEPARATOR = ",";
+const CONFIG_ARG_DISPLAY_SEPARATOR = ", ";
+const COMMAND_PRESETS = ["terminal-notifier", "notify-send"] as const;
+const TIMEOUT_PRESETS = ["1000", "3000", "5000"] as const;
+const NOTICE_WARNING = "warning" as const;
+const NOTICE_INFO = "info" as const;
+const NOTICE_ERROR = "error" as const;
+
+const pendingNotices: Notice[] = [];
+let activeRuntime: NotificationRuntime | undefined;
+let noticeKeys = new Set<string>();
+
+/** 注册配置命令，通过 TUI 菜单和输入框修改通知配置。 */
+function registerConfigCommand(pi: ExtensionAPI): void {
+  const command = {
+    description: i18n.t("configCommandDescription"),
+    getArgumentCompletions: () => [{ value: CONFIG_RESET_COMMAND, label: CONFIG_RESET_COMMAND }],
+    handler: async (args: string, ctx: ExtensionCommandContext): Promise<void> => {
+      const argument = args.trim();
+      if (argument && argument !== CONFIG_RESET_COMMAND) {
+        ctx.ui.notify(i18n.t("configCommandUsage"), NOTICE_WARNING);
+        return;
+      }
+      if (argument === CONFIG_RESET_COMMAND) {
+        try {
+          const path = saveConfig(parseConfig({}));
+          ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), NOTICE_ERROR);
+        }
+        return;
+      }
+      if (!ctx.hasUI) {
+        ctx.ui.notify(i18n.t("configCommandInteractiveOnly"), NOTICE_WARNING);
+        return;
+      }
+
+      let config: NotificationConfig;
+      try {
+        config = loadConfigWithDiagnostics().config;
+      } catch (error) {
+        ctx.ui.notify(i18n.t("configCommandInvalid", {
+          error: error instanceof Error ? error.message : String(error),
+        }), NOTICE_ERROR);
+        return;
+      }
+      const save = (next: NotificationConfig): void => {
+        try {
+          const path = saveConfig(next);
+          config = next;
+          ctx.ui.notify(i18n.t("configCommandSaved", { path }), NOTICE_INFO);
+        } catch (error) {
+          ctx.ui.notify(i18n.t("configCommandInvalid", {
+            error: error instanceof Error ? error.message : String(error),
+          }), NOTICE_ERROR);
+        }
+      };
+      const status = (enabled: boolean): string => enabled ? i18n.t("configOn") : i18n.t("configOff");
+
+      /** Selects a common scalar value and only opens text input for custom values. */
+      const chooseSettingValue = async (
+        title: string,
+        current: string,
+        options: readonly string[],
+      ): Promise<string | undefined> => {
+        const customChoice = i18n.t("configCustom");
+        const cancelChoice = i18n.t("configCancel");
+        const choices = [
+          ...options.map((value) => i18n.t("configPresetValue", { value })),
+          customChoice,
+          cancelChoice,
+        ];
+        const selected = await ctx.ui.select(title, choices);
+        if (selected === undefined || selected === cancelChoice) return undefined;
+        if (selected === customChoice) return ctx.ui.input(title, current);
+        const index = choices.indexOf(selected);
+        return index >= 0 && index < options.length ? options[index] : undefined;
+      };
+
+      while (true) {
+        const doneChoice = i18n.t("configDone");
+        const choices = [
+          i18n.t("configEnabled", { value: status(config.enabled) }),
+          i18n.t("configCommand", { value: config.adapter.command }),
+          i18n.t("configArguments", { value: config.adapter.args.join(CONFIG_ARG_DISPLAY_SEPARATOR) }),
+          i18n.t("configTimeout", { value: config.timeoutMs }),
+          doneChoice,
+        ];
+        const selected = await ctx.ui.select(i18n.t("configMenuTitle"), choices);
+        if (selected === undefined || selected === doneChoice) return;
+        const selectedIndex = choices.indexOf(selected);
+        let next: NotificationConfig | undefined;
+        if (selectedIndex === CONFIG_OPTION.enabled) {
+          next = parseConfig({ ...config, enabled: !config.enabled });
+        } else {
+          let title = i18n.t("configTimeoutInput");
+          let current = String(config.timeoutMs);
+          let options: readonly string[] = TIMEOUT_PRESETS;
+          if (selectedIndex === CONFIG_OPTION.command) {
+            title = i18n.t("configCommandInput");
+            current = config.adapter.command;
+            options = COMMAND_PRESETS;
+          } else if (selectedIndex === CONFIG_OPTION.args) {
+            title = i18n.t("configArgumentsInput");
+            current = config.adapter.args.join(CONFIG_ARG_DISPLAY_SEPARATOR);
+            options = [config.adapter.args.join(CONFIG_ARG_DISPLAY_SEPARATOR)];
+          }
+          const input = await chooseSettingValue(title, current, options);
+          if (input === undefined) continue;
+          const adapter = { ...config.adapter };
+          if (selectedIndex === CONFIG_OPTION.command) adapter.command = input.trim();
+          else if (selectedIndex === CONFIG_OPTION.args) {
+            adapter.args = input.split(CONFIG_ARG_SEPARATOR).map((arg) => arg.trim()).filter(Boolean);
+          }
+          else {
+            const timeoutMs = Number(input.trim());
+            try { next = parseConfig({ ...config, timeoutMs }); }
+            catch (error) {
+              ctx.ui.notify(i18n.t("configCommandInvalid", {
+                error: error instanceof Error ? error.message : String(error),
+              }), NOTICE_ERROR);
+            }
+          }
+          if (selectedIndex === CONFIG_OPTION.command || selectedIndex === CONFIG_OPTION.args) {
+            try { next = parseConfig({ ...config, adapter }); }
+            catch (error) {
+              ctx.ui.notify(i18n.t("configCommandInvalid", {
+                error: error instanceof Error ? error.message : String(error),
+              }), NOTICE_ERROR);
+            }
+          }
+        }
+        if (next) save(next);
+      }
+    },
+  };
+  for (const name of CONFIG_COMMAND_ALIASES) pi.registerCommand(name, command);
+}
+
+/** 导出给其他扩展使用；通知发送在后台执行，不阻塞当前 Pi 事件。 */
+export function notify(title: string, subtitle: string, message: string): void {
+  const runtime = activeRuntime ?? createRuntime();
+  activeRuntime = runtime;
+  dispatchNotification(runtime, { title, subtitle, message });
+}
+
+export default function piNotifications(pi: ExtensionAPI): void {
+  registerConfigCommand(pi);
+  const runtime = createRuntime();
+  let turnCount = 0;
+  let taskStartTime = 0;
+  activeRuntime = runtime;
+
+  pi.on("session_start", (_event, ctx) => {
+    runtime.context = ctx;
+    flushPendingNotices(ctx);
+  });
+
+  pi.on("session_shutdown", () => {
+    runtime.context = undefined;
+    if (activeRuntime === runtime) activeRuntime = undefined;
+  });
+
+  pi.on("tool_call", async (event, ctx) => {
+    runtime.context = ctx;
+    if (event.toolName !== "ask_user_question" && event.toolName !== "ask_user") return;
+
+    const project = basename(ctx.cwd);
+    const input = isRecord(event.input) ? event.input : {};
+    let prompt = i18n.t("inputNeeded");
+
+    if (event.toolName === "ask_user_question" && Array.isArray(input.questions)) {
+      const firstQuestion = isRecord(input.questions[0]) ? input.questions[0] : {};
+      const header = asString(firstQuestion.header);
+      const question = asString(firstQuestion.question);
+      const count = input.questions.length;
+      prompt = count > 1
+        ? i18n.t("multipleQuestions", {
+            prefix: header ? `[${header}] ` : "",
+            question,
+            count,
+          })
+        : `${header ? `[${header}] ` : ""}${question}`;
+    } else if (event.toolName === "ask_user") {
+      prompt = asString(input.question) || i18n.t("inputNeeded");
+    }
+
+    dispatchNotification(runtime, {
+      title: i18n.t("inputTitle", { project }),
+      subtitle: i18n.t("inputNeeded"),
+      message: prompt,
+    }, ctx);
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    runtime.context = ctx;
+    turnCount = 0;
+    taskStartTime = Date.now();
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    runtime.context = ctx;
+    turnCount++;
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    runtime.context = ctx;
+    const elapsed = taskStartTime
+      ? ((Date.now() - taskStartTime) / 1000).toFixed(1)
+      : "?";
+    const hasError = event.messages?.some(
+      (message: any) => message.role === "tool" && message.isError,
+    );
+    const project = basename(ctx.cwd);
+    const message = turnCount > 0
+      ? i18n.t("stepCount", {
+          count: turnCount,
+          seconds: elapsed,
+        })
+      : i18n.t("elapsed", { seconds: elapsed });
+
+    dispatchNotification(runtime, {
+      title: i18n.t("taskTitle", { project }),
+      subtitle: hasError ? i18n.t("taskError") : i18n.t("taskDone"),
+      message,
+    }, ctx);
+  });
+}
+
+function createRuntime(): NotificationRuntime {
+  const loaded = loadConfigWithDiagnostics();
+  const runtime: NotificationRuntime = {
+    config: loaded.config,
+    adapter: loaded.config.enabled
+      ? createArgvNotificationAdapter(
+          loaded.config.adapter,
+          loaded.config.timeoutMs,
+        )
+      : null,
+    failureReported: false,
+  };
+
+  if (loaded.diagnostic) {
+    queueNotice(
+      "config",
+      i18n.t("configInvalid", {
+        path: loaded.diagnostic.path,
+        reason: loaded.diagnostic.reason,
+      }),
+    );
+  }
+  return runtime;
+}
+
+function dispatchNotification(
+  runtime: NotificationRuntime,
+  payload: NotificationPayload,
+  context?: ExtensionContext,
+): void {
+  if (!runtime.adapter) return;
+
+  void runtime.adapter.send(payload).catch((error: unknown) => {
+    reportAdapterFailure(runtime, error, context ?? runtime.context);
+  });
+}
+
+function reportAdapterFailure(
+  runtime: NotificationRuntime,
+  error: unknown,
+  context?: ExtensionContext,
+): void {
+  if (runtime.failureReported) return;
+  runtime.failureReported = true;
+
+  const failure = asNotificationFailure(error);
+  const message = failure?.kind === "missing"
+    ? i18n.t("adapterMissing", { command: failure.command })
+    : i18n.t("sendFailed", {
+        command: failure?.command ?? runtime.config.adapter.command,
+        reason: failure?.reason ?? errorMessage(error),
+      });
+  showNotice({ level: "warning", message }, context);
+}
+
+function asNotificationFailure(error: unknown): NotificationFailure | undefined {
+  if (!isRecord(error)) return undefined;
+  if (
+    (error.kind === "missing" || error.kind === "failed") &&
+    typeof error.command === "string" &&
+    typeof error.reason === "string"
+  ) {
+    return {
+      kind: error.kind,
+      command: error.command,
+      reason: error.reason,
+    };
+  }
+  return undefined;
+}
+
+function showNotice(notice: Notice, context?: ExtensionContext): void {
+  const key = `${notice.level}:${notice.message}`;
+  if (noticeKeys.has(key)) return;
+  noticeKeys.add(key);
+
+  if (context?.ui) {
+    context.ui.notify(notice.message, notice.level);
+  } else {
+    pendingNotices.push(notice);
+  }
+}
+
+function queueNotice(key: string, message: string): void {
+  if (noticeKeys.has(key)) return;
+  noticeKeys.add(key);
+  pendingNotices.push({ level: "warning", message });
+}
+
+function flushPendingNotices(context: ExtensionContext): void {
+  for (const notice of pendingNotices.splice(0)) {
+    context.ui.notify(notice.message, notice.level);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": false,
+    "types": ["node"]
+  },
+  "include": ["index.ts", "src/**/*.ts"]
+}