@agimon-ai/doompi-notification 0.0.1-alpha.5 → 0.0.1-alpha.52

package/README.md

@@ -1,22 +1,62 @@
 # @agimon-ai/doompi-notification
 
-Desktop notifications and an animated shell-tab title for
+System and browser notifications, plus an animated shell-tab title, for
 [DoomPi](https://www.npmjs.com/package/@agimon-ai/doompi) sessions.
 
-Long agent runs are worth walking away from. This package makes that safe: the terminal tab says
-what the session is doing at a glance, and the desktop says when the agent has stopped and why.
+Long agent runs are worth walking away from. This package owns the shared `doom/notification` service,
+routes each request for the active session, and announces when the agent needs attention.
 
 ## What it does
 
-| Surface          | Behaviour                                                                                             |
-| ---------------- | ----------------------------------------------------------------------------------------------------- |
-| Shell tab title  | `π - <session or first prompt> - <repository>`, with a braille spinner while the agent works          |
-| Desktop, mid-run | one notification per dialog the agent opens on its own initiative, and per `ask_user_question` prompt |
-| Desktop, at rest | one notification when a run settles with nothing queued behind it                                     |
+| Surface          | Behavior                                                                                     |
+| ---------------- | -------------------------------------------------------------------------------------------- |
+| Shell tab title  | `π - <session or first prompt> - <repository>`, with a braille spinner while the agent works |
+| Notification API | caller-authored notices through the shared `doom/notification` Cordis service                |
+| Mid-run          | one notification for each agent-initiated dialog and each `ask_user_question` prompt         |
+| At rest          | one notification when a run settles with nothing queued behind it                            |
 
-Notifications go to `cmux notify` first, because it routes them back to the window the session
-lives in. On macOS a missing `cmux` falls back to `osascript`. Any other host stays silent rather
-than failing the turn.
+In an interactive terminal session, requests use `cmux notify` first because it routes them back to
+the session window. On macOS, a missing `cmux` falls back to `osascript`. In RPC mode, requests become
+versioned `doom-notification` session entries for a live client such as `doompi-web`. An RPC append
+failure stays silent and never falls back to a host notifier. Hosts without a supported notifier also
+stay silent.
+
+## Service usage
+
+Callers should discover the optional service through Cordis and request delivery without depending on
+a particular host:
+
+```ts
+import { DOOM_NOTIFICATION_SERVICE, readDoomNotificationService } from '@agimon-ai/doompi-core/notification';
+
+ctx.inject([DOOM_NOTIFICATION_SERVICE], (notificationContext) => {
+  void readDoomNotificationService(notificationContext)?.request({
+    body: 'Deployment needs approval',
+    level: 'warning',
+  });
+});
+```
+
+`body` is required. `title`, `subtitle`, and `level` are optional, and `level` accepts `info`,
+`warning`, or `error`. The router defaults the title to `Pi`, the subtitle to the session name or
+working-directory basename, and the level to `info`. Invalid requests, missing active sessions,
+unavailable providers, and delivery failures are silent so notifications cannot fail an agent turn.
+
+The package also wraps Pi's broad `ui.notify(message, level)` API while active, so existing extensions
+use the same route without changing their calls. If this package is muted or the process is a detached
+subagent child, it does not install that wrapper and Pi's original `ui.notify` behavior remains.
+
+## Browser delivery
+
+`doompi-web` shows full notification text only for entries received by a currently open page. Every connected
+page receives live notification entries for every attached session, not only the focused session. Permission
+is requested only from an explicit settings action.
+
+A paired installed PWA may also opt into live Web Push while closed. That payload is fixed generic copy with
+`TTL: 0`; it contains no session, prompt, response, or file data. The host keeps subscriptions only in memory,
+so there is no durable database, outbox, replay, or delivery of historical entries. The open app re-registers
+a browser-held subscription after a host restart. Device revocation or expiry, remote shutdown, browser
+disable, and expired provider endpoints remove the live subscription.
 
 ## The shell title
 
@@ -29,8 +69,8 @@ escape sequences never end up in machine-read output.
 
 ## Quiet by design
 
-- A detached subagent (`PI_SUBAGENT_CHILD`) registers nothing. It shares its parent's terminal and
-  desktop, and a second voice reporting the same run is noise.
+- A detached subagent (`PI_SUBAGENT_CHILD`) does not register this package's service or wrappers. It
+  shares its parent's terminal and desktop, and a second voice reporting the same run is noise.
 - Dialogs only notify while the agent holds the turn. A dialog the user opened is already in front
   of them.
 - An `ask_user_question` prompt notifies from its own event, and the dialog it then opens stays
@@ -42,6 +82,15 @@ escape sequences never end up in machine-read output.
 DoomPi depends on this package and activates it as fixed host core, so a DoomPi install already has
 it. It is not selectable from `.doom/modes.yaml`.
 
+The Pi and server loaders use `/extensions/pi` and `/extensions/server`, built directly from
+`src/extensions`. The root export contains reusable notification helpers and types.
+Controllers own delivery and UI integration; policy and text services live in named service folders.
+
+The Pi declaration installs its router and optional session binding before handling events.
+`onStop` restores the original UI methods and shell title before service registrations are removed.
+`onDispose` provides the same cleanup after partial startup. Detached children return before
+acquiring a Cordis connection, leaving notification ownership with the parent.
+
 ## License
 
 MIT

package/llms.txt

@@ -1,7 +1,7 @@
 # Doom Pi Notification
 
-Desktop notifications and an animated shell-tab title for Doom Pi sessions.
+Shared notification routing, browser and system delivery, and an animated shell-tab title for Doom Pi sessions.
 
 ## Resources
 
-- [Package README](./README.md): what is announced and when, the worker-thread shell-title animator, and the rules that keep a session quiet.
+- [Package README](./README.md): public `doom/notification` service usage, request defaults, RPC and interactive delivery, live-page browser permission behavior, shell-title animation, and silent fallback rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-notification",
-  "version": "0.0.1-alpha.5",
+  "version": "0.0.1-alpha.52",
   "description": "Desktop notifications and an animated shell-tab title for DoomPi sessions.",
   "keywords": [
     "ai",
@@ -16,8 +16,16 @@
     "terminal-title"
   ],
   "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/doompi/issues"
+  },
   "license": "MIT",
   "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/doompi.git",
+    "directory": "packages/foundations/doompi-notification"
+  },
   "files": [
     "dist",
     "llms.txt",
@@ -27,7 +35,8 @@
   ],
   "type": "module",
   "main": "./dist/index.cjs",
-  "types": "./dist/index.d.mts",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
   "jsnext:main": "./dist/index.mjs",
   "exports": {
     ".": {
@@ -35,31 +44,42 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./api-contracts": {
+      "types": "./dist/api-contracts.d.mts",
+      "import": "./dist/api-contracts.mjs",
+      "require": "./dist/api-contracts.cjs"
+    },
     "./extensions/pi": {
       "types": "./dist/extensions/pi.d.mts",
       "import": "./dist/extensions/pi.mjs",
       "require": "./dist/extensions/pi.cjs"
     },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.27"
+    "@agimon-ai/doompi-core": "0.0.1-alpha.75",
+    "@deepseek-ai/cordis": "4.0.2"
   },
   "devDependencies": {
-    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.26",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@types/node": "26.1.1",
-    "@vitest/coverage-v8": "4.1.10",
-    "tsdown": "0.22.14",
-    "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "@agimon-ai/doompi-build": "0.0.1-alpha.4",
+    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.70",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "26.5.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2"
+    "@earendil-works/pi-coding-agent": "0.85.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -69,6 +89,17 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "doompiServer": {
+    "entry": "./generated/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/api-contracts.mjs"
+    }
+  },
   "pi": {
     "extensions": [
       "./dist/extensions/pi.mjs"