dsh-dudu 0.0.0-stage → 0.1.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.
Files changed (238) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +115 -2
  3. package/WIDGETS.md +50 -0
  4. package/client.js +1537 -0
  5. package/cordis.patch.yml +3 -0
  6. package/dist/THIRD_PARTY_NOTICES.txt +13286 -0
  7. package/dist/apns.mjs +108 -0
  8. package/dist/assistant/assistant.mjs +230 -0
  9. package/dist/assistant/collectors/index.mjs +134 -0
  10. package/dist/assistant/collectors/migrate.mjs +66 -0
  11. package/dist/assistant/collectors/notifications.mjs +67 -0
  12. package/dist/assistant/connectors/brands.mjs +90 -0
  13. package/dist/assistant/connectors/catalog-data.mjs +48 -0
  14. package/dist/assistant/connectors/catalog.mjs +58 -0
  15. package/dist/assistant/connectors/cli.mjs +172 -0
  16. package/dist/assistant/connectors/connections.mjs +420 -0
  17. package/dist/assistant/connectors/device.mjs +86 -0
  18. package/dist/assistant/connectors/discover.mjs +199 -0
  19. package/dist/assistant/connectors/entries-file.mjs +58 -0
  20. package/dist/assistant/connectors/index.mjs +151 -0
  21. package/dist/assistant/connectors/markdown.mjs +246 -0
  22. package/dist/assistant/connectors/mcp.mjs +23931 -0
  23. package/dist/assistant/connectors/paste.mjs +553 -0
  24. package/dist/assistant/connectors/publish.mjs +179 -0
  25. package/dist/assistant/connectors/recognize.mjs +103 -0
  26. package/dist/assistant/connectors/redact.mjs +108 -0
  27. package/dist/assistant/connectors/schema.mjs +227 -0
  28. package/dist/assistant/connectors/sources.mjs +80 -0
  29. package/dist/assistant/connectors/state.mjs +55 -0
  30. package/dist/assistant/connectors/text.mjs +185 -0
  31. package/dist/assistant/connectors/toml.mjs +212 -0
  32. package/dist/assistant/dashboard/api.mjs +39 -0
  33. package/dist/assistant/dashboard/engine.mjs +1921 -0
  34. package/dist/assistant/dashboard/index.mjs +190 -0
  35. package/dist/assistant/dashboard/layout.mjs +399 -0
  36. package/dist/assistant/dashboard/widgets.mjs +72 -0
  37. package/dist/assistant/dispatch/answer.mjs +86 -0
  38. package/dist/assistant/dispatch/dsh-llm.mjs +58 -0
  39. package/dist/assistant/dispatch/hand-out.mjs +15 -0
  40. package/dist/assistant/dispatch/index.mjs +443 -0
  41. package/dist/assistant/dispatch/prompts.mjs +79 -0
  42. package/dist/assistant/dispatch/rules.mjs +146 -0
  43. package/dist/assistant/dispatch/state.mjs +129 -0
  44. package/dist/assistant/dispatch/words.mjs +60 -0
  45. package/dist/assistant/home/agent-sessions.mjs +421 -0
  46. package/dist/assistant/home/assign.mjs +287 -0
  47. package/dist/assistant/home/cards.mjs +224 -0
  48. package/dist/assistant/home/chat-home-api.mjs +30 -0
  49. package/dist/assistant/home/chat-home.mjs +93 -0
  50. package/dist/assistant/home/conversation.mjs +512 -0
  51. package/dist/assistant/home/deep-sleep.mjs +54 -0
  52. package/dist/assistant/home/dsh-sessions.mjs +391 -0
  53. package/dist/assistant/home/first-message.mjs +9 -0
  54. package/dist/assistant/home/group.mjs +279 -0
  55. package/dist/assistant/home/inbox.mjs +62 -0
  56. package/dist/assistant/home/issue-list.mjs +28 -0
  57. package/dist/assistant/home/latest.mjs +120 -0
  58. package/dist/assistant/home/native-tools.mjs +23 -0
  59. package/dist/assistant/home/projects.mjs +43 -0
  60. package/dist/assistant/home/reminders.mjs +39 -0
  61. package/dist/assistant/home/reply-stream.mjs +49 -0
  62. package/dist/assistant/home/session-catalog.mjs +126 -0
  63. package/dist/assistant/home/session-cleanup.mjs +27 -0
  64. package/dist/assistant/home/session-facts.mjs +136 -0
  65. package/dist/assistant/home/session-search.mjs +112 -0
  66. package/dist/assistant/home/session-takeover.mjs +82 -0
  67. package/dist/assistant/home/session-titles.mjs +135 -0
  68. package/dist/assistant/home/source-collector.mjs +343 -0
  69. package/dist/assistant/home/task-session.mjs +292 -0
  70. package/dist/assistant/home/tidy.mjs +28 -0
  71. package/dist/assistant/home/tools.mjs +247 -0
  72. package/dist/assistant/identity.mjs +5 -0
  73. package/dist/assistant/inbox/api.mjs +288 -0
  74. package/dist/assistant/inbox/records.mjs +343 -0
  75. package/dist/assistant/inbox/store.mjs +474 -0
  76. package/dist/assistant/issues/api.mjs +244 -0
  77. package/dist/assistant/issues/attachments.mjs +105 -0
  78. package/dist/assistant/issues/contract.mjs +123 -0
  79. package/dist/assistant/issues/create-with-attachments.mjs +15 -0
  80. package/dist/assistant/issues/index.mjs +1166 -0
  81. package/dist/assistant/issues/labels.mjs +89 -0
  82. package/dist/assistant/issues/links.mjs +71 -0
  83. package/dist/assistant/issues/message.mjs +22 -0
  84. package/dist/assistant/issues/references.mjs +85 -0
  85. package/dist/assistant/issues/schema.mjs +203 -0
  86. package/dist/assistant/issues/source.mjs +20 -0
  87. package/dist/assistant/issues/summary.mjs +7 -0
  88. package/dist/assistant/issues/tidy.mjs +178 -0
  89. package/dist/assistant/issues/workflow.mjs +154 -0
  90. package/dist/assistant/memory/files.mjs +324 -0
  91. package/dist/assistant/memory/index.mjs +457 -0
  92. package/dist/assistant/memory/secrets.mjs +81 -0
  93. package/dist/assistant/memory/skills.mjs +91 -0
  94. package/dist/assistant/memory/tidy.mjs +570 -0
  95. package/dist/assistant/memory/turns.mjs +255 -0
  96. package/dist/assistant/needs-you-color.mjs +13 -0
  97. package/dist/assistant/project.mjs +265 -0
  98. package/dist/assistant/rules.mjs +41 -0
  99. package/dist/assistant/schedule/cron.mjs +819 -0
  100. package/dist/assistant/schedule/index.mjs +137 -0
  101. package/dist/assistant/segment.mjs +21 -0
  102. package/dist/assistant/sessions/activity-projection.mjs +4144 -0
  103. package/dist/assistant/sessions/deep-sleep.mjs +35 -0
  104. package/dist/assistant/sessions/index.mjs +563 -0
  105. package/dist/assistant/sessions/read-receipts.mjs +59 -0
  106. package/dist/assistant/sessions/readers.mjs +384 -0
  107. package/dist/assistant/sessions/session-activity.mjs +159 -0
  108. package/dist/assistant/sessions/session-state.mjs +67 -0
  109. package/dist/assistant/sessions/states.mjs +132 -0
  110. package/dist/assistant/settings.mjs +134 -0
  111. package/dist/assistant/tasks/contract.mjs +2 -0
  112. package/dist/assistant/tasks/host.mjs +113 -0
  113. package/dist/assistant/tasks/index.mjs +226 -0
  114. package/dist/assistant/tasks/timing.mjs +55 -0
  115. package/dist/assistant/tasks/tools.mjs +32 -0
  116. package/dist/assistant/templates.mjs +103 -0
  117. package/dist/assistant/widgets/local.mjs +63 -0
  118. package/dist/client.js +2786 -0
  119. package/dist/computer-use/engine.mjs +771 -0
  120. package/dist/computer-use/provider-context.mjs +50 -0
  121. package/dist/computer-use/provider.mjs +27 -0
  122. package/dist/computer-use/registration.mjs +61 -0
  123. package/dist/context-page-reads.mjs +108 -0
  124. package/dist/conversation-search.mjs +61 -0
  125. package/dist/conversation-timing.mjs +36 -0
  126. package/dist/desktop-runtime.mjs +70 -0
  127. package/dist/dsbot-control.mjs +263 -0
  128. package/dist/dsh-market-page-reads.mjs +200 -0
  129. package/dist/dsh-mobile-frontend.mjs +754 -0
  130. package/dist/dsh-session-history.mjs +38 -0
  131. package/dist/dsh-subagents.mjs +11 -0
  132. package/dist/dsh-tools.mjs +20 -0
  133. package/dist/legacy-state.mjs +47 -0
  134. package/dist/mobile-page-adapter.mjs +738 -0
  135. package/dist/mobile-page-locale.mjs +20 -0
  136. package/dist/native-assistant.mjs +168 -0
  137. package/dist/native-board.mjs +409 -0
  138. package/dist/native-bridge.mjs +2668 -0
  139. package/dist/native-conversation-reads.mjs +109 -0
  140. package/dist/native-conversation.mjs +361 -0
  141. package/dist/native-diagnostics.mjs +50 -0
  142. package/dist/native-file-transfers.mjs +24 -0
  143. package/dist/native-files.mjs +267 -0
  144. package/dist/native-images.mjs +13 -0
  145. package/dist/native-locale.mjs +43 -0
  146. package/dist/native-markdown-images.mjs +7220 -0
  147. package/dist/native-navigation-icons.mjs +16 -0
  148. package/dist/native-navigation.mjs +350 -0
  149. package/dist/native-notifications.mjs +119 -0
  150. package/dist/native-page-policy.mjs +401 -0
  151. package/dist/native-page-rpc.mjs +246 -0
  152. package/dist/native-pages.mjs +489 -0
  153. package/dist/native-questions.mjs +120 -0
  154. package/dist/native-server.mjs +550 -0
  155. package/dist/native-session-activity.mjs +184 -0
  156. package/dist/native-settings.mjs +487 -0
  157. package/dist/native-strings.mjs +193 -0
  158. package/dist/native-videos.mjs +48 -0
  159. package/dist/pairing-devices.mjs +288 -0
  160. package/dist/phone/settings.css +2 -0
  161. package/dist/phone/settings.js +50 -0
  162. package/dist/phone-pages.mjs +76 -0
  163. package/dist/providers/activity.mjs +43 -0
  164. package/dist/providers/async.mjs +74 -0
  165. package/dist/providers/catalog.mjs +33 -0
  166. package/dist/providers/commands.mjs +39 -0
  167. package/dist/providers/cron-tools.mjs +168 -0
  168. package/dist/providers/drivers/claude-tools.mjs +98 -0
  169. package/dist/providers/drivers/claude.mjs +84 -0
  170. package/dist/providers/drivers/codex-tools.mjs +58 -0
  171. package/dist/providers/drivers/codex.mjs +97 -0
  172. package/dist/providers/drivers/pi-tools.mjs +89 -0
  173. package/dist/providers/drivers/pi.mjs +106 -0
  174. package/dist/providers/drivers/universal-tools.mjs +152 -0
  175. package/dist/providers/drivers/universal.mjs +117 -0
  176. package/dist/providers/foreground.mjs +37 -0
  177. package/dist/providers/goal.mjs +34 -0
  178. package/dist/providers/harness-bridge.mjs +566 -0
  179. package/dist/providers/index.mjs +258 -0
  180. package/dist/providers/input-delivery.mjs +194 -0
  181. package/dist/providers/input.mjs +38 -0
  182. package/dist/providers/jobs.mjs +105 -0
  183. package/dist/providers/mirror-tools.mjs +50 -0
  184. package/dist/providers/native/balance.mjs +75 -0
  185. package/dist/providers/native/cached-content-index.mjs +95 -0
  186. package/dist/providers/native/claude-child-usage.mjs +103 -0
  187. package/dist/providers/native/claude-history.mjs +164 -0
  188. package/dist/providers/native/claude-search.mjs +45 -0
  189. package/dist/providers/native/claude-store.mjs +176 -0
  190. package/dist/providers/native/codex-history.mjs +117 -0
  191. package/dist/providers/native/codex-metrics.mjs +47 -0
  192. package/dist/providers/native/codex-store.mjs +184 -0
  193. package/dist/providers/native/content-cache-worker.mjs +134 -0
  194. package/dist/providers/native/content-index.mjs +100 -0
  195. package/dist/providers/native/history.mjs +27 -0
  196. package/dist/providers/native/images.mjs +157 -0
  197. package/dist/providers/native/index.mjs +778 -0
  198. package/dist/providers/native/overview.mjs +28 -0
  199. package/dist/providers/native/preview.mjs +10 -0
  200. package/dist/providers/native/repair.mjs +106 -0
  201. package/dist/providers/native/running.mjs +68 -0
  202. package/dist/providers/native/search-worker.mjs +32 -0
  203. package/dist/providers/native/session-events.mjs +104 -0
  204. package/dist/providers/native/session-info.mjs +33 -0
  205. package/dist/providers/native/sync.mjs +219 -0
  206. package/dist/providers/native/text.mjs +12 -0
  207. package/dist/providers/oar-pi.mjs +362932 -0
  208. package/dist/providers/oar-resident.mjs +107 -0
  209. package/dist/providers/oar-runtimes.mjs +48600 -0
  210. package/dist/providers/oar.mjs +652 -0
  211. package/dist/providers/permission.mjs +16 -0
  212. package/dist/providers/quota/claude.mjs +171 -0
  213. package/dist/providers/quota/codex.mjs +80 -0
  214. package/dist/providers/quota/deepseek.mjs +66 -0
  215. package/dist/providers/quota/index.mjs +38 -0
  216. package/dist/providers/quota/service.mjs +81 -0
  217. package/dist/providers/quota/store.mjs +40 -0
  218. package/dist/providers/quota/system-proxy.mjs +31217 -0
  219. package/dist/providers/stats.mjs +4129 -0
  220. package/dist/providers/teams.mjs +347 -0
  221. package/dist/providers/usage.mjs +34 -0
  222. package/dist/qr.mjs +20 -0
  223. package/dist/session-diagnostics.mjs +56 -0
  224. package/dist/session-history-coalescing.mjs +75 -0
  225. package/dist/session-storage-witness.mjs +34 -0
  226. package/dist/web-page-http.mjs +394 -0
  227. package/icon.png +0 -0
  228. package/index.mjs +1129 -0
  229. package/locale/en.json +6 -0
  230. package/locale/zh.json +6 -0
  231. package/package.json +42 -4
  232. package/widget-testing.d.ts +5 -0
  233. package/widget-testing.mjs +52 -0
  234. package/widget-ui.d.ts +7 -0
  235. package/widget-ui.mjs +16 -0
  236. package/widget.css +20 -0
  237. package/widget.d.ts +138 -0
  238. package/widget.mjs +7 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 weiwenhao
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,116 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="docs/images/logo-wide.png" width="300" alt="Dudu">
4
+
5
+ ### An efficient multi-agent collaboration assistant built on DSH
6
+
7
+ [![License: MIT](https://img.shields.io/badge/license-MIT-green?style=flat-square)](LICENSE) ![version](https://img.shields.io/badge/version-0.1.0%20beta-orange?style=flat-square) ![Node.js](https://img.shields.io/badge/node-%E2%89%A5%2024-339933?style=flat-square&logo=node.js&logoColor=white) ![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-0.2.2--rc.1-4D6BFE?style=flat-square)
8
+
9
+ [Design philosophy](#design-philosophy) • [Features](#features) • [Development guide](#development-guide) • **English** · [简体中文](README.zh-CN.md)
10
+
11
+ </div>
12
+
13
+ Dudu is a multi-agent collaboration workspace built on [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness). To install it, enter dsh-dudu in DSH's "Add plugin".
14
+
15
+ <div align="center">
16
+ <img src="docs/images/hero.en.png" width="900" alt="Dudu inside DSH Desktop: the conversations of the issues on the left with one of them open, the Inbox on the top right and the Office below it">
17
+ </div>
18
+
19
+ Dudu can be managed from your phone too: on iOS, search for dudu in the App Store; on Android, install the apk from [GitHub Release](https://github.com/weiwenhao/dudu/releases).
20
+
21
+ <div align="center">
22
+ <img src="docs/images/phone.en.png" alt="The mobile app, from left to right: the conversation list; the chat; the menu that opens from + in the chat; tasks" width="900">
23
+ </div>
24
+
25
+ The workspace's home page is a dashboard: you can arrange its layout freely and develop widgets of your own.
26
+
27
+ <div align="center">
28
+ <img src="docs/images/dashboard.en.png" alt="The dashboard in edit mode: the Issues widget on the left uses the board layout, the widget on the right is being resized, and the blue frame and 6×4 show its new size" width="900">
29
+ </div>
30
+
31
+ ## Design philosophy
32
+
33
+ Built on [oar](https://github.com/botiverse/oar), Dudu brings many kinds of agents (TUIs) together in one GUI, which solves the problem of managing multiple agents. It manages task status efficiently with a board, and agent status efficiently with sessions.
34
+
35
+ The picture above is the workspace I use every day. I usually keep more than 30 agent sessions open, including Claude, Codex and DeepSeek, for personal projects as well as work projects. Dudu solves the problem of working efficiently in exactly this kind of multi-agent, multi-task setting. It has already replaced Herdr/Orca, which I had always used before.
36
+
37
+ Dudu is not a Grok Bot type of product. In a Bot type of product, a person only needs to chat with a few Bots to get a large number of tasks done, but I believe that in real work, talking directly to the agent doing the task is more accurate than having a Bot relay it.
38
+
39
+ Personal agents such as OpenClaw and Muse have long been very popular, and the DSH foundation makes it very easy to create one, so I also created the assistant **Dudu**. It is a personal agent similar to Muse, with a memory management system of its own. The assistant can operate every feature: the session board, writing widgets, connectors, collectors, scheduled tasks and so on. In the future it will take on more work to lighten my workload.
40
+
41
+ ## Features
42
+
43
+ - Supports the DSH, Claude, Codex, Pi, Grok, Kimi, OpenCode, Antigravity, CodeBuddy, Devin, Factory, Qwen and Qoder agents, deeply integrated into the GUI.
44
+ - Easily import the DSH, Claude and Codex sessions you already have.
45
+ - Manage every feature by talking to Dudu, the personal assistant.
46
+ - Inactive agents go into deep sleep automatically, so they do not take up memory.
47
+ - Collaboration and session management are built around the Issue board.
48
+ - Sessions are managed like a chat app, so you can quickly find the ones whose work is done.
49
+ - Manage DSH sessions from your phone too: it is effectively the mobile client of DSH, on both iOS and Android.
50
+ - Collectors gather all your information in one place.
51
+ - With scheduled tasks you can send any agent to do anything, such as managing email or daily inspections.
52
+ - Check your Claude, Codex and DeepSeek quota at a glance.
53
+ - Every widget on the dashboard can be dragged and resized, and you can ask Dudu to write widgets of your own.
54
+ - There is also a cute office: when you are bored, see what your agents are up to.
55
+
56
+
57
+ ## Data directories
58
+
59
+ | Directory | Contents |
60
+ | :-- | :-- |
61
+ | `~/.dsh` | DSH's data directory, i.e. `DSH_HOME` |
62
+ | `~/.dsh/dudu/home` | The assistant's home directory, also the working directory of its sessions: its Markdown files (`AGENTS.md`, `SOUL.md`, `USER.md`, `MEMORY.md` and so on) and the widgets it writes (`widgets/`). The location can be changed in Settings |
63
+ | `~/.dsh/dudu/assistant/` | The assistant's settings and databases (`settings.json`, `issues.db` and so on) |
64
+
65
+ ## Development guide
66
+
67
+ Bug reports and suggestions are welcome in [GitHub Issues](https://github.com/weiwenhao/dudu/issues), and so are pull requests. For a larger change, please open an Issue first to talk about your idea.
68
+
69
+ ### Development environment
70
+
71
+ You need Node.js 24 or later, Git and [DSH](https://deepseek.com/harness). Building the iOS app also needs Xcode and [XcodeGen](https://github.com/yonaskolb/XcodeGen); building the Android app also needs Android Studio.
72
+
73
+ ```sh
74
+ git clone https://github.com/weiwenhao/dudu.git
75
+ cd dudu
76
+ npm install
77
+ ```
78
+
79
+ ### Run
80
+
81
+ ```sh
82
+ npm run desktop:update # package and install into the DSH Desktop on this computer; macOS only for now
83
+ npm run native:install # build the iOS app and install it on an iPhone
84
+ npm run android:install # build the Android app and install it on an emulator
85
+ ```
86
+
87
+ Before building the iOS app, replace the developer team and the bundle ID in `native/project.yml` with your own.
88
+
89
+ Without `desktop:update`, run `npm run package:desktop`, then install `dsh-dudu-<version>.tgz` from `.local/release/` in DSH's "Add plugin".
90
+
91
+ ### Test
92
+
93
+ ```sh
94
+ npm run typecheck
95
+ npm test # unit tests
96
+ npm run test:e2e # end-to-end tests, slower
97
+ ```
98
+
99
+ ### Developing widgets
100
+
101
+ Just ask Dudu to write one. It writes an `.mjs` file under `widgets/` in its home directory, and a few seconds later the widget shows up under "Add widget" in "Edit layout": no plugin to install, no code to clone. See [WIDGETS.md](host/dudu-plugin/WIDGETS.md) for how to write one.
102
+
103
+ To publish a widget for others to use, make it a DSH plugin: see the [widget template](examples/dudu-widget/README.md).
104
+
105
+ ## Recommended communities
106
+
107
+ <table>
108
+ <tr>
109
+ <td width="200" align="center"><a href="https://linux.do/"><img src="docs/images/friend-linuxdo.png" height="56" alt="LINUX DO"></a></td>
110
+ <td><b><a href="https://linux.do/">LINUX DO</a></b>: "Where possible begins." Its culture is sincerity, friendliness, unity and professionalism.</td>
111
+ </tr>
112
+ <tr>
113
+ <td width="200" align="center"><a href="https://www.v2ex.com/"><img src="docs/images/friend-v2ex.png" height="56" alt="V2EX"></a></td>
114
+ <td><b><a href="https://www.v2ex.com/">V2EX</a></b>: a community of creative workers, talking about programming, design, hardware, games and more.</td>
115
+ </tr>
116
+ </table>
package/WIDGETS.md ADDED
@@ -0,0 +1,50 @@
1
+ # Writing a widget for Dudu
2
+
3
+ A widget is one of the draggable panels on the Dudu dashboard (Issues, Office, Inbox are widgets). You write one as a single file. There is nothing to install and no build step.
4
+
5
+ ## Where it goes
6
+
7
+ `<assistant home>/widgets/<name>.mjs`, with a lowercase name made of letters, digits and dashes, for example `widgets/clock.mjs`. The file is a JavaScript module of at most 256 KB.
8
+
9
+ The dashboard looks at the folder every few seconds. A new file shows up in the add list (Edit layout, Add widget). A changed file replaces the old one, also where it is already on the board. A deleted file removes its widget. A widget's id is `local.<name>`, so the file name is the only name to choose.
10
+
11
+ ## The file
12
+
13
+ Default-export a function. It receives `{ React, h, defineWidget, Frame, Row, Empty, Badge, WidgetNumber, ProgressBar }` and returns what `defineWidget` returns.
14
+
15
+ ```js
16
+ export default ({ h, defineWidget, Frame, WidgetNumber }) => defineWidget({
17
+ label: 'Clock',
18
+ min: { w: 3, h: 2 },
19
+ size: { w: 4, h: 3 },
20
+ }, function Clock({ useIssues }) {
21
+ const { value } = useIssues({ tab: 'active', limit: 1 });
22
+ return h(Frame, { title: 'Clock' }, h(WidgetNumber, { value: value?.total ?? '-', label: 'Active issues' }));
23
+ });
24
+ ```
25
+
26
+ - There are no imports. Everything comes through the argument. `h` is `React.createElement`, and `React` has the hooks (`React.useState`, `React.useEffect`, ...).
27
+ - `label` is the name in the add list. `description` is optional.
28
+ - `min` is the smallest size whose content still reads. `size` is the size it gets when it is added, and is not smaller than `min`. Sizes count dashboard cells: fifteen columns, and rows about as tall as a column is wide. `size` may use `'fill'` for every column or every row the window shows. Both are required.
29
+ - `needs` lists what the widget reads (`issues`, `quota`, `inputs`, `sessions`, `network`). It defaults to an empty list. `preview` is an optional image for the add list, as a `data:` URL.
30
+
31
+ ## What the component gets
32
+
33
+ The component receives these props:
34
+
35
+ - `size: { cols, rows, width, height }` and `editing`.
36
+ - Read-only hooks `useIssues(view)`, `useQuota()`, `useInputs()` and `useSessions(query)`. Each returns `{ status, value }` and follows the real data while the widget is mounted. `useInputs()` is what the Inbox shows: the records the collectors collected.
37
+ - Actions `openIssue(id)`, `openSession(session)`, `takeOverSession(session)` and the read `readSession(session)`.
38
+ - `renderIssues()` renders the Issues interface.
39
+
40
+ `Frame`, `Row`, `Empty`, `Badge`, `WidgetNumber` and `ProgressBar` come with the host's styles. Plain elements and DSH's `--dsw-*` tokens work as well. The full types are in `widget.d.ts`, next to this file.
41
+
42
+ ## Rules
43
+
44
+ - Any size from `min` up must fit: show whole rows and scroll inside when the content is longer.
45
+ - Content follows its own size (container queries), not the screen width.
46
+ - Respect reduced motion. Label icon buttons with `aria-label`.
47
+
48
+ ## Did it load?
49
+
50
+ The dashboard writes how each file loaded to `<assistant home>/widgets/status.json`: `{ "widgets": { "<name>": { "ok": true } } }`, or `{ "ok": false, "error": "..." }` for a file that failed. A file that does not export a function, or whose declaration is incomplete, fails there with the reason. The file is written while the dashboard is open, a few seconds after the widget file changes. A widget that fails while it renders shows an error where it sits on the board.