@soffits/dsh-notify-inbox 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ - Asks: whatever keeps the person's list of open asks (a Todo) writes them to `<person>/asks.json`, and with that file there it alone decides **Needs you**. Each open ask is one item, with the notifications of its thread folded in; one that left the file shows as Handled ("Settled"). An ask's `points` show beside its title, and its own buttons, title and session win over its notifications'.
6
+ - Reply where you read: an ask (or a notification with `session`) has a reply box that sends your answer into the session that asked, as you, through `@soffits/dsh-ui-actions`' `start`, with the ask quoted in.
7
+ - **Breaking:** a new group **Urgent** on top: interrupts default to it (done and snooze move them on as before). `needs-you` is no longer a default for interrupts or for notifications with done or snooze buttons; it is for asks.
8
+ - No polling: the plugin watches the folders (`fs.watch`) for the page's change notices and pushes new records the moment the inbox file changes, and the Web UI follows the events stream for its counts instead of a timer. The `pollSeconds` option is gone (an old value is ignored).
9
+
10
+ ## 0.5.0
11
+
12
+ - A new page, built from DSH's own components and the shared [@soffits/dsh-ui-kit](https://github.com/soffits/dsh-ui-kit), which is now required. Notifications are grouped as Needs you, Live, Handled and To know, with the counts on top, an optional summary line (`summary.json`) and each domain's icon on a tinted tile (`domains` setting). [docs/ui.md](docs/ui.md) lists what is DSH's and what is the plugin's own.
13
+ - Records may carry `attention`, `thread`, `live` and `handled`. Without `attention`, interrupts and notifications with done or snooze buttons need you and the rest is to know. A needs-you item marked done moves to Handled, a snoozed one waits under To know, a live item drops to To know when its time is over.
14
+ - Notifications with the same `thread` are one item with their history beneath; a live thread's newest notification replaces the item in place.
15
+ - New notifications and changes show up while the page is open, through `GET /api/notify-inbox/events` (Server-Sent Events), with a short cue on what changed. The page polls while the stream is down.
16
+ - The filters are Needs you and All (Unread is gone: unread items carry a dot). Items stay where they first showed until you leave the view. Mark unread is in the opened item. Push settings moved into the ⋯ menu.
17
+ - An inbox file rewritten in place is read again even when it grew.
18
+ - Needs DSH 0.2.2-rc.1 or later.
3
19
  ## 0.4.0
4
20
 
5
21
  - Suggested next steps: a notification's `step` actions show as their own buttons (from @soffits/dsh-ui-actions 0.2.0). A tap is recorded here like done and snooze, as the event `ui.action.step` with who pressed it, then the step is sent to the assistant; the row says "Started".
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # dsh-notify-inbox
2
2
 
3
- A notification inbox for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Something outside DSH (your assistant's notification router, a cron script, a watcher) files notifications as JSON lines, one folder per person. The plugin shows each signed-in person their own inbox in the Web UI, keeps read and unread per person on the server, pushes new ones to the browsers and installed home-screen apps they turned notifications on for, and gives every notification buttons: ask the agent about it, mark it done, remind me later.
3
+ A notification inbox for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH). Something outside DSH (a notification router, a cron script, a watcher) files notifications as JSON lines, one folder per person. The plugin shows each signed-in person their own inbox in the Web UI, keeps read and unread per person on the server, pushes new ones to the browsers and installed home-screen apps they turned notifications on for, and gives every notification buttons: ask the agent about it, mark it done, remind me later.
4
+
5
+ The page sorts notifications by what they ask of you: **Urgent** (a leak, a door left open: on top until you deal with it), **Needs you** (what waits on your answer, which you can reply to right there), **Live** (a flight's status, a running job, updated in place), **Handled** (what was done for you, in one quiet line) and **To know**. Notifications about one thing fold into one item with its history underneath, new ones appear while the page is open, and an optional line at the top says what matters now. It is built from DSH's own components, so it looks like the rest of the Web UI in light and dark ([docs/ui.md](docs/ui.md) says which few pieces aren't DSH's, and why).
4
6
 
5
7
  The contract is files, so nothing gets lost while DSH restarts: the writer keeps appending, and the plugin pushes whatever arrived once it's back.
6
8
 
@@ -10,6 +12,12 @@ The contract is files, so nothing gets lost while DSH restarts: the writer keeps
10
12
  npx @deepseek-ai/dsh plugin --profile web add @soffits/dsh-notify-inbox@latest
11
13
  ```
12
14
 
15
+ It needs two small shared plugins next to it, [@soffits/dsh-ui-kit](https://github.com/soffits/dsh-ui-kit) (icons, live time, history) and [@soffits/dsh-ui-actions](https://github.com/soffits/dsh-ui-actions) (the buttons):
16
+
17
+ ```sh
18
+ npx @deepseek-ai/dsh plugin --profile web add @soffits/dsh-ui-kit@latest @soffits/dsh-ui-actions@latest
19
+ ```
20
+
13
21
  Restart `dsh web`. The inbox appears in the sidebar. Then set `dataDir` in a profile override of the `notify-inbox` row:
14
22
 
15
23
  ```yaml
@@ -31,7 +39,8 @@ Restart `dsh web`. The inbox appears in the sidebar. Then set `dataDir` in a pro
31
39
  | `peopleFile`, `peopleKey` | | A JSON file with more of the same mapping, re-read when it changes; `peopleKey` picks a top-level key. |
32
40
  | `vapidFile` | `<dataDir>/.push/vapid.json` | The Web Push key pair, made on first start with mode 600. Keep it: a new key means every device subscribes again. |
33
41
  | `vapidSubject` | `mailto:admin@example.invalid` | A contact push services can reach. Set your own. |
34
- | `pollSeconds` | `5` | How often new lines are looked for (to push them). |
42
+ | `domains` | `{}` | How each `domain` is drawn, on top of the built-in defaults (`mail`, `money`, `health`, `travel`, `home`, `orders`...): `{ "legal": { "icon": "scale", "tone": "violet" } }`. `icon` is a [Lucide](https://lucide.dev) name the kit bundles; `tone` (`ok`, `warn`, `bad`, `accent`, `violet`, `muted`) is usually left out, since an item's colour says what it needs. |
43
+ | `summaryHours` | `12` | How long the summary line is shown after it was written. |
35
44
 
36
45
  **Who sees what.** With a mapping, every request is checked on the server: a person sees, marks and presses only their own inbox, and a request without a verified identity sees nothing. The identity comes from any plugin that provides a `requestIdentity` service (`current()` → `{ provider, issuer, id, name } | null`), such as [dsh-oidc](https://github.com/soffits/dsh-oidc) 0.3.0-alpha.9 or later. Without a mapping (a DSH only you use), you see every folder.
37
46
 
@@ -51,12 +60,37 @@ Append one JSON object per line to `<dataDir>/<person>/inbox.jsonl` (person ids
51
60
  {"destination": "phone", "type": "ntfy", "ok": false, "detail": "timed out"}]}
52
61
  ```
53
62
 
54
- - `id` (required, unique), `time` (required, ISO 8601). `lane: "interrupt"` marks it urgent (red dot, high push urgency).
63
+ - `id` (required, unique), `time` (required, ISO 8601). `lane: "interrupt"` makes it urgent (on top, a red tile, high push urgency).
55
64
  - `title`, `spoken` (one short line: the push body), `text` (the full text), `links` (http/https).
56
65
  - `files`: attachments the writer copied to `<dataDir>/<person>/files/<id>/<name>`; only those are served, and only to that person.
57
66
  - `push: false` files it without a push. `test: true` labels it as a test.
58
67
  - `routed`: where else the notification went and whether that worked; shown under the text.
59
68
  - `actions`: buttons, see below.
69
+ - `attention`: the group, `urgent`, `needs-you`, `live`, `handled` or `info` ("To know"). Left out, it follows from the rest: `handled` when `handled` is set, `live` when `live` is, `urgent` for an interrupt, else `info`. An urgent item the person marked done moves to Handled, a snoozed one waits under To know until it comes back. `needs-you` is for asks (below).
70
+ - `session`: the session that asked, for a notification that waits on the person's answer; the item then has a reply box (below).
71
+ - `thread`: notifications with the same thread are one item, the newest on top and the older ones as its history (three reminders about one task).
72
+ - `live`: `{ "until"?, "progress"?: { "from", "to" } }`. The thread's newest notification replaces the item in place, shown as live until `until` (or six hours after its last update), with a bar from `from` to `to`.
73
+ - `handled`: `{ "text", "at"? }`, what was done for the person, shown as one quiet line with a check.
74
+
75
+ An optional `<dataDir>/<person>/summary.json`, `{ "text": "...", "at": "<ISO time>" }`, is the sentence shown above the items for `summaryHours`.
76
+
77
+ ## Asks
78
+
79
+ What waits on the person's answer (a decision, a pick, a small step for someone else's work) usually lives in a list of their own, such as a Todo. Whatever keeps that list writes the open ones to `<dataDir>/<person>/asks.json` each time it changes; with that file there, it alone says what shows under **Needs you**:
80
+
81
+ ```json
82
+ {"v": 1, "asks": [
83
+ {"id": "todo:1a2b3c4d", "title": "Pick the lamp", "text": "White or oak? The white one is 39.", "time": "2026-11-17T15:50:12Z",
84
+ "next": "2026-11-18", "due": "2026-11-20", "points": 3, "session": "<session id>", "domain": "todo",
85
+ "actions": [{"kind": "done", "id": "done", "payload": {"source": "todo", "uuid": "1a2b..."}, "inverse": {"kind": "reopen", "payload": {}}},
86
+ {"kind": "snooze", "id": "snooze", "payload": {"source": "todo", "uuid": "1a2b..."}}]}]}
87
+ ```
88
+
89
+ - Each open ask is one item, whether or not a notification was ever filed about it. Notifications whose `thread` is the ask's `id` fold into it, and the ask's own buttons, title and `session` win. When the ask leaves the file it was settled where it lives: its notifications show as Handled ("Settled").
90
+ - `points` (shown as a small "+3" beside the title) is what dealing with it earns where the list keeps such a game; leave it out otherwise. `next` and `due` are days.
91
+ - With a `session`, the opened item has a reply box. The reply goes into that session as the person (through `@soffits/dsh-ui-actions`' `start`, DSH's own session prompt), with the ask quoted in, so the conversation that asked carries on with the answer; the page offers to open it.
92
+ - A press on an ask's buttons is an action event like any other (`source.record` is the ask's id), for whatever keeps the list to act on.
93
+ - Without `asks.json` nothing changes: notifications keep the group they were filed with.
60
94
 
61
95
  A line `{"v": 1, "type": "handled", "record": "<id>", "press": "<press id>", "action": "done", "result": "done", "time": "..."}` tells the inbox that a press on that record was dealt with (`result: "snoozed"` with `until` shows when it comes back). Bad lines are skipped and counted.
62
96
 
@@ -78,7 +112,7 @@ The page shows the press as waiting until a `handled` line for it shows up.
78
112
 
79
113
  ## Push notifications
80
114
 
81
- Open the inbox on the device and press **Turn on**. The browser picks its own push service, and the plugin only ever talks to that service, with the message encrypted end to end (RFC 8291, VAPID per RFC 8292, no third-party library):
115
+ Open the inbox on the device, open its **⋯** menu and choose **Turn on**. The browser picks its own push service, and the plugin only ever talks to that service, with the message encrypted end to end (RFC 8291, VAPID per RFC 8292, no third-party library):
82
116
 
83
117
  - **iPhone and iPad** (iOS 16.4+): add DSH to the Home Screen, open it from there, then turn notifications on. Pushes go through Apple's service.
84
118
  - **Chrome, Edge, Android**: pushes go through Google's Firebase Cloud Messaging, so they don't arrive where Google is blocked.
@@ -86,6 +120,10 @@ Open the inbox on the device and press **Turn on**. The browser picks its own pu
86
120
 
87
121
  Tapping a notification opens the inbox on it. A device whose subscription expired is dropped the first time its push service says so.
88
122
 
123
+ ## Live updates
124
+
125
+ An open Web UI follows `GET /api/notify-inbox/events`, a Server-Sent Events stream that says when the caller's inbox changed (records, read marks, presses, the summary or the asks), and fetches again; the browser reconnects by itself when the stream drops. The plugin watches the data folder and each person's folder (`fs.watch`), so a change is noticed when the file changes, and new records are pushed the same moment; nothing polls. The data folder must be on a local file system for that (a network share may not report changes).
126
+
89
127
  ## Languages
90
128
 
91
129
  The page follows DSH's language. Its words live in `locale/<tag>.json` (`ui` for the page, `meta` for the plugin list): English, French and Chinese ship. Another language is one more file with the same keys; anything it leaves out comes from its primary language (`pt` for `pt-BR`), then English. Notification text is shown as it was sent.