omp-notify-tool

Latest in v0.2.4 | OMP 15 schema 兼容修复

• Uses runtime-compatible enum schemas when pi.StringEnum is unavailable | pi.StringEnum 不可用时使用 runtime 兼容的枚举 schema
• Avoids bare JSON schema fallbacks that break Type.Optional | 避免裸 JSON schema fallback 触发 Type.Optional 崩溃
• Keeps progress updates separate from question, wait, and completion notifications | 将进度提示与 question、wait 和完成提醒分离
• Falls open when UI notification is unavailable or fails | UI 通知不可用或失败时保持 fail-open

中文 | English

---

中文

omp-notify-tool 为 OMP 和 Pi-family runtime 提供模型可调用的非阻塞 notify 工具。

notify 用于进度、阶段切换和后台状态提示，不要求用户立即响应。参数语义直接贴合 OMP/Pi UI 通知能力，并通过 OMP/Pi extension 入口注册到宿主运行时。

功能一览

• 非阻塞进度提示 — 模型可以调用 notify({ message, variant }) 汇报进度，不把纯进度升级成提问。
• OMP/Pi 双入口 — npm 包同时声明 omp.extensions 与 legacy pi.extensions，入口均为 ./src/extension.ts。
• 明确交互边界 — 需要用户响应、确认、授权、最终交接或无安全工作可继续时，不要使用 notify。
• 完成提醒边界 — 如果需要 Agent 完成后提醒人回来，请使用 pi-notify 或 pi-poly-notify。本包不是完成提醒插件。
• Fail-open — headless/subagent、无 UI、ctx.ui.notify 缺失或通知失败时，对模型可见文本仍为 ok，真实投递状态保留在 details。

---

安装

选项 A：让 LLM 帮你安装

把下面这段话丢给 OMP / Claude Code / Cursor 等任意 LLM Agent：

请先查看 omp-notify-tool 最新 GitHub Release 正文里的安装或升级说明，然后严格执行其中带明确版本号的 OMP 安装命令。不要省略版本号，不要使用 latest。安装后运行 `omp plugin doctor` 确认插件可用。如果 OMP 已经运行，安装或升级后重启会话再验证。参考说明：https://github.com/jiwangyihao/omp-notify-tool/releases/latest

选项 B：手动安装

当前版本：

omp plugin install omp-notify-tool@0.2.4

当前 OMP CLI（已验证 omp/14.9.3）不接受 npm: 前缀；请使用上面的裸包名版本化命令。

安装后检查插件状态：

omp plugin doctor

如果 OMP 已在运行，安装或升级后重启会话再验证。

步骤指引

1. 读取本仓库最新 GitHub Release 正文：

   https://github.com/jiwangyihao/omp-notify-tool/releases/latest

2. 提取其中带明确版本号的安装命令。当前版本示例：

   omp plugin install omp-notify-tool@0.2.4
   

   当前 OMP CLI（已验证 omp/14.9.3）不接受 npm: 前缀；不要把命令改成 npm:omp-notify-tool@...。

3. 直接执行该命令。不要省略版本号，不要使用 latest，不要手动编辑 OMP/Pi 配置。

4. 安装后运行：

   omp plugin doctor
   

5. 如果 OMP 已经运行，重启后再进行功能验证。

验证

让 Agent 调用 notify，例如：

{
  "message": "Running verification",
  "variant": "info"
}

在 interactive/RPC UI 可用时，应看到非阻塞通知；在 headless/subagent 或无 UI 场景中，工具对模型可见文本仍返回 ok，不会中断主任务，真实状态记录在 details.delivered 与 details.reason。

---

本地开发

omp plugin link <path-to-this-repo>
bun test
npm pack --dry-run --json

工具参数

模型调用 notify 时只应传入 message 和可选 variant：

{
  "message": "Running verification",
  "variant": "info"
}

• message：必填，非空字符串。
• variant：可选，只能是 info、warning、error；缺省为 info。

使用边界

notify 只用于进度、阶段切换和后台状态。需要用户响应、确认、授权、最终交接或无安全工作可继续时，不要使用 notify。

需要等待时使用宿主提供的 wait 或等价机制；需要提问或确认时使用 question 或宿主对应的交互工具。

如果你需要 Agent 完成后提醒人回来，请使用 pi-notify 或 pi-poly-notify。本包不是完成提醒插件，也不提供桌面完成通知、声音、Webhook、邮件或移动推送。

运行时模式

• OMP interactive：当当前会话有 UI 且 ctx.ui.notify 可用时，通知会作为非阻塞 UI 提示展示。
• OMP RPC：当宿主提供 RPC UI notify 通道时，通知按 fire-and-forget 方式发送，不要求模型等待用户响应。
• headless/subagent：无 UI、后台或子代理场景对模型可见文本仍返回 ok；工具会 fail open，并在 details 中记录未投递原因。
• Pi-family runtime：同一个 npm 包通过 legacy pi.extensions 入口加载。目标 Pi runtime 仍需提供兼容的 extension API 和 ctx.ui.notify 能力；未验证的安装命令或运行时行为不在本文中写成事实。

相关版本

• 使用 OpenCode？请安装 opencode-notify-tool：

  opencode plugin opencode-notify-tool@0.1.0 --force -g
  

• 两个包都提供模型可调用的非阻塞 notify 进度提示，但宿主适配层和可用 variant 集合不同。不要把 OMP/Pi 包直接装到 OpenCode，也不要把 OpenCode 包直接装到 OMP/Pi。

---

English

omp-notify-tool gives OMP and Pi-family runtimes a model-callable, non-blocking notify tool.

Use it for progress updates, phase changes, and background status messages that do not require an immediate user response. Use question or the host runtime's interactive tools when a real user decision, confirmation, authorization, or final handoff is required.

What You Get

• Non-blocking progress updates — agents can call notify({ message, variant }) without turning progress into a prompt.
• OMP/Pi dual entry — the package declares both omp.extensions and legacy pi.extensions, both pointing to ./src/extension.ts.
• Clear interaction boundary — notify is not a replacement for question, wait, permission approval, or final responses.
• Completion-notification boundary — use pi-notify or pi-poly-notify if you need a completion notification when the agent finishes.
• Fail-open behavior — missing UI, headless/subagent mode, or notification failures do not interrupt the main agent task.

---

Installation

Option A: Let an LLM do it

Paste this into any OMP / Claude Code / Cursor style LLM agent:

First read the latest GitHub Release for omp-notify-tool, then execute the exact versioned OMP install command from the release notes. Do not omit the version number or use latest. After installation, run `omp plugin doctor` to confirm the plugin is available. If OMP is already running, restart the session before verification. Reference: https://github.com/jiwangyihao/omp-notify-tool/releases/latest

Option B: Manual setup

Current version:

omp plugin install omp-notify-tool@0.2.4

Current OMP CLI behavior (verified with omp/14.9.3) does not accept the npm: prefix; use the bare package name command above.

Verify installation:

omp plugin doctor

If OMP is already running, restart it before verification.

Step-by-Step Instructions

1. Read the latest GitHub Release body for this repository:

   https://github.com/jiwangyihao/omp-notify-tool/releases/latest

2. Extract the exact versioned install command. Current version example:

   omp plugin install omp-notify-tool@0.2.4
   

   Current OMP CLI behavior (verified with omp/14.9.3) does not accept the npm: prefix; do not rewrite the command as npm:omp-notify-tool@....

3. Execute that command directly. Do not omit the version number, do not use latest, and do not hand-edit OMP/Pi configuration.

4. After installation, run:

   omp plugin doctor
   

5. If OMP is already running, restart before feature verification.

Verification

Ask the agent to call notify, for example:

{
  "message": "Running verification",
  "variant": "info"
}

In interactive/RPC UI modes, a non-blocking notification should be displayed. In headless/subagent or no-UI modes, the visible tool text still returns ok; delivery state is recorded in details.delivered and details.reason.

---

Local Development

omp plugin link <path-to-this-repo>
bun test
npm pack --dry-run --json

Tool Input

{
  "message": "Running verification",
  "variant": "info"
}

• message: required, non-empty string.
• variant: optional, one of info, warning, or error; defaults to info.

Runtime Modes

• OMP interactive: shows a non-blocking UI notification when ctx.ui.notify is available.
• OMP RPC: sends a fire-and-forget UI notification request when the host provides that channel.
• headless/subagent: visible tool text still returns ok; delivery failures stay in details, and the tool fails open without interrupting the main task.
• Pi-family runtime: loads through the legacy pi.extensions package entry. The target runtime must provide compatible extension APIs and ctx.ui.notify.

Companion Package

• Using OpenCode? Install opencode-notify-tool:

  opencode plugin opencode-notify-tool@0.1.0 --force -g
  

• Both packages provide a model-callable, non-blocking notify progress tool, but their host adapters and supported variant values are different. Do not install the OMP/Pi package into OpenCode or the OpenCode package into OMP/Pi.

License

MPL-2.0; see LICENSE.