@clagentic/console 1.12.0-beta.3 → 1.13.0-beta.1

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 (243) hide show
  1. package/README.md +7 -1
  2. package/bin/cli.js +18 -15
  3. package/lib/agent-roster-ws.js +38 -13
  4. package/lib/agent-roster.js +111 -12
  5. package/lib/agents.js +68 -33
  6. package/lib/atomic-install.js +334 -0
  7. package/lib/build-changes.js +33 -4
  8. package/lib/build-sha.json +2 -2
  9. package/lib/build-update-offer.js +12 -0
  10. package/lib/chat-width.js +31 -0
  11. package/lib/cli/agent-usage.js +126 -0
  12. package/lib/cli/arg-validation.js +1 -1
  13. package/lib/cli/compact-output.js +69 -0
  14. package/lib/cli/ipc-subcommands.js +92 -67
  15. package/lib/cli/output.js +28 -0
  16. package/lib/cli/restart-verb.js +132 -0
  17. package/lib/cli/schedule-input-subcommands.js +45 -8
  18. package/lib/cli/session-subcommands.js +37 -11
  19. package/lib/cli/settings-subcommands.js +74 -0
  20. package/lib/cli-transcript-title.js +56 -3
  21. package/lib/client-files.js +79 -0
  22. package/lib/daemon.js +100 -28
  23. package/lib/default-avatar-color.js +4 -0
  24. package/lib/drain.js +58 -10
  25. package/lib/mcp-tool-input.js +2 -2
  26. package/lib/model-families.js +49 -1
  27. package/lib/notify/type-registry.js +4 -0
  28. package/lib/notify/types.js +7 -4
  29. package/lib/pages.js +13 -63
  30. package/lib/permission-summary.js +12 -16
  31. package/lib/plan-usage-reader.js +70 -0
  32. package/lib/project-connection.js +4 -2
  33. package/lib/project-filesystem.js +6 -7
  34. package/lib/project-notifications.js +55 -8
  35. package/lib/project-prompt-expiry-settings.js +42 -0
  36. package/lib/project-sessions.js +52 -0
  37. package/lib/project-settings-gate.js +98 -0
  38. package/lib/project-user-mention.js +3 -2
  39. package/lib/project.js +1 -1
  40. package/lib/prompt-expiry-settings.js +49 -0
  41. package/lib/prompt-expiry.js +24 -3
  42. package/lib/prompt-kinds/codecs.js +6 -2
  43. package/lib/public/app.js +36 -36
  44. package/lib/public/css/admin.css +156 -170
  45. package/lib/public/css/agent-messages.css +24 -24
  46. package/lib/public/css/agent-picker.css +90 -38
  47. package/lib/public/css/agent-roster.css +61 -27
  48. package/lib/public/css/at-agents.css +10 -10
  49. package/lib/public/css/base.css +207 -184
  50. package/lib/public/css/chat-layout.css +228 -0
  51. package/lib/public/css/command-palette.css +86 -88
  52. package/lib/public/css/diagnostics.css +78 -204
  53. package/lib/public/css/diff.css +10 -10
  54. package/lib/public/css/filebrowser.css +32 -60
  55. package/lib/public/css/home-hub.css +100 -100
  56. package/lib/public/css/icon-strip.css +195 -238
  57. package/lib/public/css/input.css +191 -212
  58. package/lib/public/css/login-panel.css +16 -16
  59. package/lib/public/css/loop.css +96 -187
  60. package/lib/public/css/mention.css +49 -110
  61. package/lib/public/css/menus.css +162 -169
  62. package/lib/public/css/messages.css +49 -123
  63. package/lib/public/css/mobile-nav.css +207 -264
  64. package/lib/public/css/notifications-center.css +45 -124
  65. package/lib/public/css/overlay.css +269 -0
  66. package/lib/public/css/overlays.css +134 -156
  67. package/lib/public/css/playbook.css +41 -41
  68. package/lib/public/css/profile.css +43 -112
  69. package/lib/public/css/rewind.css +112 -112
  70. package/lib/public/css/scheduler-modal.css +27 -135
  71. package/lib/public/css/scheduler.css +204 -210
  72. package/lib/public/css/server-settings.css +173 -239
  73. package/lib/public/css/session-search.css +20 -20
  74. package/lib/public/css/settings-nav.css +197 -0
  75. package/lib/public/css/sidebar.css +213 -304
  76. package/lib/public/css/skills.css +121 -135
  77. package/lib/public/css/sticky-notes.css +114 -200
  78. package/lib/public/css/stt.css +17 -26
  79. package/lib/public/css/team-panel.css +36 -36
  80. package/lib/public/css/team-view.css +9 -9
  81. package/lib/public/css/title-bar.css +83 -100
  82. package/lib/public/css/tooltip.css +10 -10
  83. package/lib/public/css/user-settings.css +78 -131
  84. package/lib/public/css/user-shell.css +125 -29
  85. package/lib/public/index.html +178 -177
  86. package/lib/public/manifest.json +0 -2
  87. package/lib/public/modules/admin.js +54 -92
  88. package/lib/public/modules/agent-avatar.js +134 -3
  89. package/lib/public/modules/agent-messages.js +2 -1
  90. package/lib/public/modules/agent-picker.js +23 -21
  91. package/lib/public/modules/agent-roster-groups.js +128 -0
  92. package/lib/public/modules/agent-roster.js +40 -11
  93. package/lib/public/modules/app-connection.js +13 -1
  94. package/lib/public/modules/app-cursors.js +9 -9
  95. package/lib/public/modules/app-favicon.js +8 -16
  96. package/lib/public/modules/app-header.js +28 -19
  97. package/lib/public/modules/app-history-replay.js +67 -4
  98. package/lib/public/modules/app-home-hub.js +15 -0
  99. package/lib/public/modules/app-loop-ui.js +41 -47
  100. package/lib/public/modules/app-loop-wizard.js +9 -10
  101. package/lib/public/modules/app-messages.js +32 -36
  102. package/lib/public/modules/app-misc.js +22 -92
  103. package/lib/public/modules/app-modals.js +98 -0
  104. package/lib/public/modules/app-notifications.js +124 -135
  105. package/lib/public/modules/app-panels.js +28 -32
  106. package/lib/public/modules/app-projects.js +30 -40
  107. package/lib/public/modules/app-rate-limit.js +26 -9
  108. package/lib/public/modules/app-rendering.js +128 -110
  109. package/lib/public/modules/app-skills-install.js +6 -4
  110. package/lib/public/modules/assistant-identity.js +55 -0
  111. package/lib/public/modules/at-agents.js +3 -0
  112. package/lib/public/modules/build-guard.js +25 -11
  113. package/lib/public/modules/chat-width-choice.js +75 -0
  114. package/lib/public/modules/chat-width-prefs.js +52 -0
  115. package/lib/public/modules/chat-width.js +102 -0
  116. package/lib/public/modules/collapsible-text.js +36 -4
  117. package/lib/public/modules/command-palette.js +28 -34
  118. package/lib/public/modules/context-sources.js +3 -5
  119. package/lib/public/modules/diagnostics.js +130 -129
  120. package/lib/public/modules/info-panel.js +31 -0
  121. package/lib/public/modules/injected-identity.js +8 -8
  122. package/lib/public/modules/input-list-menu.js +39 -0
  123. package/lib/public/modules/input.js +22 -21
  124. package/lib/public/modules/markdown.js +10 -11
  125. package/lib/public/modules/mcp-ui.js +4 -14
  126. package/lib/public/modules/mention.js +100 -229
  127. package/lib/public/modules/message-header.js +80 -0
  128. package/lib/public/modules/message-participants.js +39 -0
  129. package/lib/public/modules/mobile-action-sheet.js +46 -0
  130. package/lib/public/modules/mobile-nav-sheet.js +104 -0
  131. package/lib/public/modules/model-families.js +41 -4
  132. package/lib/public/modules/note-order.js +39 -0
  133. package/lib/public/modules/notifications.js +35 -52
  134. package/lib/public/modules/overlay-history.js +73 -19
  135. package/lib/public/modules/overlay-menu.js +123 -0
  136. package/lib/public/modules/overlay-modal.js +186 -0
  137. package/lib/public/modules/overlay-registry.js +392 -0
  138. package/lib/public/modules/overlay-stack.js +110 -0
  139. package/lib/public/modules/overlay.js +117 -0
  140. package/lib/public/modules/popover-position.js +18 -2
  141. package/lib/public/modules/preference-sync.js +28 -0
  142. package/lib/public/modules/profile.js +24 -49
  143. package/lib/public/modules/project-settings.js +27 -172
  144. package/lib/public/modules/prompt-expiry-controls.js +46 -0
  145. package/lib/public/modules/prompt-kinds/command-summary.js +149 -0
  146. package/lib/public/modules/prompt-kinds/permission.js +70 -92
  147. package/lib/public/modules/prompts.js +1 -2
  148. package/lib/public/modules/qrcode.js +6 -21
  149. package/lib/public/modules/queued-button.js +15 -2
  150. package/lib/public/modules/rewind.js +9 -3
  151. package/lib/public/modules/schedule-time.js +32 -7
  152. package/lib/public/modules/scheduled-outbox.js +51 -18
  153. package/lib/public/modules/scheduler-config.js +87 -127
  154. package/lib/public/modules/scheduler.js +29 -26
  155. package/lib/public/modules/serialized-save.js +79 -0
  156. package/lib/public/modules/server-settings.js +75 -65
  157. package/lib/public/modules/session-grants.js +16 -19
  158. package/lib/public/modules/session-list-avatars.js +98 -0
  159. package/lib/public/modules/session-vendor-state.js +86 -0
  160. package/lib/public/modules/settings-access.js +35 -0
  161. package/lib/public/modules/settings-hub.js +125 -0
  162. package/lib/public/modules/settings-nav.js +182 -0
  163. package/lib/public/modules/shell-line.js +24 -0
  164. package/lib/public/modules/sidebar-mobile.js +151 -195
  165. package/lib/public/modules/sidebar-projects.js +88 -129
  166. package/lib/public/modules/sidebar-sessions.js +66 -34
  167. package/lib/public/modules/sidebar.js +2 -2
  168. package/lib/public/modules/skills.js +11 -26
  169. package/lib/public/modules/sticky-notes.js +19 -16
  170. package/lib/public/modules/stt.js +9 -23
  171. package/lib/public/modules/terminal.js +86 -90
  172. package/lib/public/modules/theme-choice.js +126 -0
  173. package/lib/public/modules/theme-colors.js +19 -0
  174. package/lib/public/modules/theme-prefs.js +121 -0
  175. package/lib/public/modules/theme.js +227 -605
  176. package/lib/public/modules/tool-palette.js +7 -17
  177. package/lib/public/modules/tools.js +8 -10
  178. package/lib/public/modules/user-settings.js +59 -115
  179. package/lib/public/modules/user-shell.js +9 -2
  180. package/lib/public/modules/utils.js +10 -12
  181. package/lib/public/modules/vendor-picker.js +4 -2
  182. package/lib/public/modules/vendor-registry.js +1 -2
  183. package/lib/public/style.css +3 -1
  184. package/lib/public/sw.js +9 -2
  185. package/lib/public/theme-core.js +411 -0
  186. package/lib/request-body.js +70 -0
  187. package/lib/sdk-bridge.js +227 -88
  188. package/lib/sdk-message-processor.js +44 -16
  189. package/lib/server-admin.js +198 -200
  190. package/lib/server-auth.js +16 -13
  191. package/lib/server-dm.js +4 -3
  192. package/lib/server-settings.js +177 -130
  193. package/lib/server.js +87 -36
  194. package/lib/session-background-tasks.js +79 -0
  195. package/lib/session-directory.js +138 -13
  196. package/lib/session-input-ipc.js +2 -0
  197. package/lib/session-input.js +39 -5
  198. package/lib/session-list-avatars.js +16 -0
  199. package/lib/session-reclaim.js +37 -25
  200. package/lib/session-vendor.js +37 -0
  201. package/lib/sessions.js +99 -34
  202. package/lib/settings-ipc.js +60 -0
  203. package/lib/settings-registry.js +86 -0
  204. package/lib/terminal-manager.js +17 -5
  205. package/lib/theme-files.js +132 -0
  206. package/lib/theme-seed.js +136 -0
  207. package/lib/themes/clagentic-dark.json +13 -6
  208. package/lib/themes/clagentic-light.json +12 -5
  209. package/lib/updater.js +6 -4
  210. package/lib/usage-store.js +97 -10
  211. package/lib/users-preferences.js +118 -19
  212. package/lib/users.js +19 -10
  213. package/lib/vendor-catalog.js +130 -0
  214. package/lib/ws-schema.js +4 -2
  215. package/lib/yoke/adapters/claude.js +81 -1
  216. package/lib/yoke/adapters/codex-user-shell.js +87 -23
  217. package/lib/yoke/adapters/codex.js +89 -5
  218. package/lib/yoke/codex-binary.js +59 -0
  219. package/package.json +1 -1
  220. package/scripts/check-test-count.js +5 -0
  221. package/scripts/install-local-test.js +50 -9
  222. package/scripts/write-build-sha.js +18 -2
  223. package/lib/public/css/channel-layout.css +0 -329
  224. package/lib/themes/ayu-light.json +0 -9
  225. package/lib/themes/catppuccin-latte.json +0 -9
  226. package/lib/themes/catppuccin-mocha.json +0 -9
  227. package/lib/themes/dracula.json +0 -9
  228. package/lib/themes/everforest-light.json +0 -9
  229. package/lib/themes/everforest.json +0 -9
  230. package/lib/themes/github-light.json +0 -9
  231. package/lib/themes/gruvbox-dark.json +0 -9
  232. package/lib/themes/gruvbox-light.json +0 -9
  233. package/lib/themes/monokai.json +0 -9
  234. package/lib/themes/nord-light.json +0 -9
  235. package/lib/themes/nord.json +0 -9
  236. package/lib/themes/one-dark.json +0 -9
  237. package/lib/themes/one-light.json +0 -9
  238. package/lib/themes/rose-pine-dawn.json +0 -9
  239. package/lib/themes/rose-pine.json +0 -9
  240. package/lib/themes/solarized-dark.json +0 -9
  241. package/lib/themes/solarized-light.json +0 -9
  242. package/lib/themes/tokyo-night-light.json +0 -9
  243. package/lib/themes/tokyo-night.json +0 -9
package/README.md CHANGED
@@ -61,6 +61,10 @@ To skip the postinstall script:
61
61
  npm install -g @clagentic/console --ignore-scripts
62
62
  ```
63
63
 
64
+ ### Updating while commands are running
65
+
66
+ The in-app update and the startup update install the new build beside the current one and swap it in, so `clagentic-console` stays on `PATH` the whole time and a command run during the update keeps working. A plain `npm install -g @clagentic/console` run by hand is npm's own install: npm removes the old command before it links the new one, so a `clagentic-console` call made in those few seconds can exit 127 (command not found). If a script or hook calls `clagentic-console`, retry on exit 127, or update from inside the app.
67
+
64
68
  ## What it does
65
69
 
66
70
  - **Real team accounts.** Every team member gets their own login. Multiple users connect to the same Console daemon simultaneously — each with their own session history, project access, and tool approval flow. No shared credentials, no per-user installs.
@@ -85,6 +89,8 @@ npm install -g @clagentic/console --ignore-scripts
85
89
 
86
90
  - **MCP servers.** Built-in ask-user and browser servers. User-configured MCPs via `~/.clagentic/mcp.json`. Works in both Claude and Codex sessions.
87
91
 
92
+ - **Themes.** Dark, Light, or Follow system, from User Settings, Appearance (on a phone, the More sheet). Drop your own theme file into `~/.clagentic/console/themes/` to add a custom theme to the same choice; see [Themes](docs/guides/THEMES.md).
93
+
88
94
  - **Your data, your machine.** Sessions are JSONL, settings are JSON, knowledge is Markdown. No cloud relay, no proprietary database.
89
95
 
90
96
  - **Clagentic: Lite (optional).** If [Clagentic: Lite](https://clagentic.ai/tools) is installed, project settings surface per-project enrollment controls and system settings add a global auto-enroll toggle. Console detects it passively — nothing changes if it isn't present.
@@ -196,7 +202,7 @@ To install the current working-tree build globally and test it as a real end-use
196
202
  npm run install:local-test
197
203
  ```
198
204
 
199
- This runs `npm pack` (which respects the `files` list in `package.json`, so you get exactly what would ship to npm), installs the resulting tarball globally with `npm install -g`, and removes the tarball. The result is indistinguishable from `npm install -g @clagentic/console` — no symlinks, no `node_modules` shortcuts.
205
+ This runs `npm pack` (which respects the `files` list in `package.json`, so you get exactly what would ship to npm), installs the resulting tarball globally, and removes the tarball. The tarball is installed into a staging prefix and swapped into the global prefix with renames, so `clagentic-console` stays on `PATH` during the install. The result is the same files and links as `npm install -g @clagentic/console` — no symlinks, no `node_modules` shortcuts.
200
206
 
201
207
  When done testing, uninstall with:
202
208
 
package/bin/cli.js CHANGED
@@ -102,6 +102,11 @@ if (args[0] === "schedule-input") {
102
102
  return;
103
103
  }
104
104
 
105
+ if (args[0] === "settings") {
106
+ require("../lib/cli/settings-subcommands").runSettingsVerb(args.slice(1));
107
+ return;
108
+ }
109
+
105
110
  var port = _isDev ? 2635 : 2633;
106
111
  var useHttps = true;
107
112
  var forceMkcert = false;
@@ -111,6 +116,7 @@ var autoYes = false;
111
116
  var cliPin = null;
112
117
  var shutdownMode = false;
113
118
  var restartMode = false;
119
+ var jsonMode = false;
114
120
  var noRestart = false;
115
121
  var addPath = null;
116
122
  var removePath = null;
@@ -164,6 +170,8 @@ for (var i = 0; i < args.length; i++) {
164
170
  shutdownMode = true;
165
171
  } else if (args[i] === "--restart") {
166
172
  restartMode = true;
173
+ } else if (args[i] === "--json") {
174
+ jsonMode = true;
167
175
  } else if (args[i] === "--no-restart") {
168
176
  noRestart = true;
169
177
  } else if (args[i] === "--add") {
@@ -191,25 +199,19 @@ for (var i = 0; i < args.length; i++) {
191
199
  } else if (args[i] === "--os-users") {
192
200
  osUsersMode = true;
193
201
  } else if (args[i] === "-h" || args[i] === "--help") {
194
- console.log("Usage: clagentic-console [-p|--port <port>] [--host <address>] [--no-https] [--no-update] [--debug] [-y|--yes] [--pin <pin>] [--shutdown] [--restart] [--no-restart]");
202
+ console.log("Usage: clagentic-console [-p|--port <port>] [--host <address>] [--no-https] [--no-update] [--debug] [-y|--yes] [--pin <pin>] [--shutdown] [--restart [--json]] [--no-restart]");
195
203
  console.log(" clagentic-console --add <path> Add a project to the running daemon");
196
204
  console.log(" clagentic-console --remove <path> Remove a project from the running daemon");
197
205
  console.log(" clagentic-console --list List registered projects");
198
206
  console.log(" clagentic-console --activity-diagnostics Print activity-divergence probe totals as JSON (agent-readable)");
199
207
  console.log(" clagentic-console --usage Print account usage per vendor and rate-limit bucket as JSON, with how fresh each reading is and why (agent-readable)");
200
208
  console.log(" clagentic-console --process-build-status Print the running process's loaded build SHA as JSON (agent-readable)");
201
- console.log(" clagentic-console open-session (--project <slug> | --to <address>) --prompt <text|-> [--vendor <id>] [--agent <name>] [--name <session-name>] [--visibility shared|private] [--permission-mode <mode>] [--settings <path>] [--initiator <kind>] [--context-note <text>] [--from <name>] [--from-session <id>] Open a session and run a first prompt (prints JSON)");
202
- console.log(" clagentic-console send-input (--project <slug> --session <id> | --to <address> | --reply) --prompt <text|-> [--initiator <kind>] [--context-note <text>] [--from <name>] [--from-session <id>] Send input to a session, resuming it if needed (prints JSON; exit 3 ambiguous, 4 not found by address)");
203
- console.log(" clagentic-console end-session (--project <slug> --session <id> | --to <address>) [--from <name>] [--from-session <id>] [--reason <text>] Stand one live session down, even one blocked on a permission prompt; history is kept and the session resumes by id (prints JSON; exit 3 ambiguous, 4 not found by address)");
204
- console.log(" clagentic-console answer-prompt (--project <slug> --session <id> | --to <address>) --request <id> --decision <allow|deny|allow_always|text> [--from <name>] [--from-session <id>] Answer one pending prompt of a live session, as the browser would (prints JSON; exit 3 ambiguous, 4 not found by address)");
205
- console.log(" clagentic-console list-sessions [--project <slug>] [--agent <name>] [--vendor <id>] [--state live|idle|reaped|any] List the console's sessions (prints JSON)");
206
- console.log(" clagentic-console list-outbound --session <vendor-session-id> [--project <slug>] [--since <dur>] [--kind sent|opens] List what a session (by vendor session id, see list-sessions) sent out with send-input and open-session: target, prompt, time, initiator (prints JSON; read-only; kept 30 days by default)");
207
- console.log(" clagentic-console schedule-input create --session <id> [--project <slug>] (--in <dur> | --at <time> | --every <dur> (--until <time> | --count <n>)) (--prompt <text|-> | --prompt-file <path>) Send text into a session later, once or on a repeat with an end (prints JSON)");
208
- console.log(" clagentic-console schedule-input list [--session <id>] [--project <slug>] [--state armed|done|ended|any] List scheduled input, from the browser or the CLI (prints JSON)");
209
- console.log(" clagentic-console schedule-input delete --id <id> [--project <slug>] Cancel a scheduled input");
210
- console.log(" <dur> is minutes or parts like 90, 10m, 1h30m; <time> is a local HH:MM (a past one means tomorrow)");
211
- console.log(" <address> is <agent>@<project>, <vendor>@<project> (a plain session) or @<project>, each with an optional /<session-name>");
212
- console.log(" Several matches resolve live over idle over reaped; /<session-name> names one session exactly");
209
+ // The agent verbs' lines come from the one usage source their own --help reads.
210
+ require("../lib/cli/agent-usage").topLevelLines().forEach(function (line) { console.log(line); });
211
+ console.log(" Each of these takes -h or --help for its own usage");
212
+ console.log(" clagentic-console settings get <key> Print one server-wide setting's value and default as JSON (agent-readable; known keys: promptExpiryMinutes, chatWidth, sessionListAvatars)");
213
+ console.log(" clagentic-console settings set <key> <value> Change a server-wide setting; prints the value read back from the daemon (value is JSON when it parses; exit 1 if refused)");
214
+ console.log(" clagentic-console settings list List the settings with their values and defaults as JSON");
213
215
  console.log(" clagentic-console release list-betas List promotable beta versions (maintainer/release-engineering)");
214
216
  console.log(" clagentic-console daemon Run the daemon in the foreground (used by the systemd unit)");
215
217
  console.log("");
@@ -223,7 +225,8 @@ for (var i = 0; i < args.length; i++) {
223
225
  console.log(" -y, --yes Skip interactive prompts (accept defaults)");
224
226
  console.log(" --pin <pin> Set 6-digit PIN (use with --yes)");
225
227
  console.log(" --shutdown Shut down the running relay daemon");
226
- console.log(" --restart Restart the running relay daemon");
228
+ console.log(" --restart Restart the running relay daemon and wait for the new process (reports sessions in flight)");
229
+ console.log(" --json With --restart: print one JSON report; exit 0 only if the new process loaded the installed build");
227
230
  console.log(" --no-restart Do not auto-restart on crash (useful for debugging crash state)");
228
231
  console.log(" --add <path> Add a project directory (use '.' for current)");
229
232
  console.log(" --remove <path> Remove a project directory");
@@ -252,7 +255,7 @@ if (shutdownMode) {
252
255
 
253
256
  // --- Handle --restart before anything else ---
254
257
  if (restartMode) {
255
- handleRestart();
258
+ handleRestart(jsonMode);
256
259
  return;
257
260
  }
258
261
 
@@ -5,9 +5,15 @@
5
5
  // agent_avatar_set c2s {key, avatar}: choose an avatar for a seen agent;
6
6
  // avatar is {style, seed}, {custom} or null (clear)
7
7
  // agent_roster s2c the roster as this connection may read it:
8
- // {agents: [{key, firstSeen, lastSeen, places,
9
- // avatar}]}, a place being {source, project,
10
- // lastSeen}. Sent on connect and on request; each
8
+ // {agents: [{key, lastSeen, places,
9
+ // avatar, group, vendor}], catalog}, a place being
10
+ // {source, project, lastSeen}; lastSeen is the latest
11
+ // among the readable places, and no firstSeen is
12
+ // sent; group is "agent",
13
+ // "helper" or "model" and vendor the vendor whose
14
+ // list held the key (null for an agent); catalog is
15
+ // what the vendors reported, [{vendor, models,
16
+ // helpers}] (lib/vendor-catalog.js). Sent on connect and on request; each
11
17
  // place is limited to projects the connection can
12
18
  // read, and an agent with none is left out.
13
19
  // agent_roster_changed s2c the roster changed; ask again. It carries no
@@ -29,10 +35,23 @@ function callerOf(ws) {
29
35
  // service: { listFor(caller) } or null. A service that cannot say what a caller
30
36
  // may read answers nothing rather than everything.
31
37
  function rosterMessage(service, caller) {
32
- return { type: ROSTER, agents: service && typeof service.listFor === "function" ? service.listFor(caller) : [] };
38
+ var message = { type: ROSTER, agents: service && typeof service.listFor === "function" ? service.listFor(caller) : [] };
39
+ // Only a service that holds a vendor catalog adds it, so a roster with none sends the shape it always did.
40
+ if (service && typeof service.catalogSnapshot === "function") message.catalog = service.catalogSnapshot();
41
+ return message;
33
42
  }
34
43
 
35
- // deps: { service ({ listFor(caller), setAvatar(caller, key, avatar) }, or null), sendTo(ws, obj) }
44
+ // The change nudge: the burst-coalescing notifier of the Team view's agent
45
+ // messages, sending only {type: CHANGED}. deps: { broadcast(msg), delayMs? }.
46
+ function createRosterNotifier(deps) {
47
+ return require("./team-traffic-ws").createNotifier({
48
+ broadcast: deps.broadcast,
49
+ delayMs: deps.delayMs,
50
+ build: function () { return { type: CHANGED }; },
51
+ });
52
+ }
53
+
54
+ // deps: { service ({ listFor(caller), setAvatar(caller, key, avatar) resolving to the outcome }, or null), sendTo(ws, obj) }
36
55
  function createWsHandlers(deps) {
37
56
  var service = deps.service;
38
57
 
@@ -56,14 +75,19 @@ function createWsHandlers(deps) {
56
75
  deps.sendTo(ws, { type: SET_RESULT, key: key, ok: false, error: "the agent roster is not available here" });
57
76
  return true;
58
77
  }
59
- var outcome;
60
- try {
61
- outcome = service.setAvatar(callerOf(ws), msg.key, msg.avatar);
62
- } catch (e) {
63
- console.error("[agent-roster] setting an avatar failed:", e && e.message ? e.message : e);
64
- outcome = { ok: false, error: "the avatar could not be saved" };
65
- }
66
- deps.sendTo(ws, outcome.ok ? { type: SET_RESULT, key: key, ok: true } : { type: SET_RESULT, key: key, ok: false, error: outcome.error });
78
+ // setAvatar answers once the write has landed or failed, so the reply is
79
+ // sent then; the message is still ours the moment it is taken.
80
+ new Promise(function (resolve) { resolve(service.setAvatar(callerOf(ws), msg.key, msg.avatar)); })
81
+ .catch(function (e) {
82
+ console.error("[agent-roster] setting an avatar failed:", e && e.message ? e.message : e);
83
+ return { ok: false, error: "the avatar could not be saved" };
84
+ })
85
+ .then(function (outcome) {
86
+ deps.sendTo(ws, outcome.ok ? { type: SET_RESULT, key: key, ok: true } : { type: SET_RESULT, key: key, ok: false, error: outcome.error });
87
+ })
88
+ .catch(function (e) {
89
+ console.error("[agent-roster] replying to an avatar change failed:", e && e.message ? e.message : e);
90
+ });
67
91
  return true;
68
92
  }
69
93
  return false;
@@ -74,6 +98,7 @@ function createWsHandlers(deps) {
74
98
 
75
99
  module.exports = {
76
100
  createWsHandlers: createWsHandlers,
101
+ createRosterNotifier: createRosterNotifier,
77
102
  rosterMessage: rosterMessage,
78
103
  callerOf: callerOf,
79
104
  REQUEST: REQUEST,
@@ -26,6 +26,10 @@ var FILE_VERSION = 1;
26
26
  var SOURCE = Object.freeze({ SESSION: "session", SUBAGENT: "subagent", SENDER: "sender" });
27
27
  var SOURCES = Object.freeze(Object.keys(SOURCE).map(function (k) { return SOURCE[k]; }));
28
28
 
29
+ // The Team view groups. A catalog answers "model" or "helper"; anything it does
30
+ // not know is a named agent.
31
+ var GROUP = Object.freeze({ AGENT: "agent", HELPER: "helper", MODEL: "model" });
32
+
29
33
  var MAX_AGENTS = 1000;
30
34
  var MAX_KEY_LENGTH = 128;
31
35
  var MAX_PLACES = 20;
@@ -112,6 +116,10 @@ function senderKey(sender) {
112
116
  // two apart.
113
117
  var NOT_SEEN = "that agent has not been seen";
114
118
 
119
+ // The reply when a chosen avatar could not be written to disk. Fixed text: it
120
+ // names no project, agent or path.
121
+ var SAVE_FAILED = "the avatar could not be saved";
122
+
115
123
  function loadFile(file) {
116
124
  var raw;
117
125
  try {
@@ -149,6 +157,8 @@ function copyEntry(entry) {
149
157
  // mayReadProject(slug, caller) true when the caller may read that project
150
158
  // (slug is null for a sighting that named none). Absent,
151
159
  // no caller may read anything.
160
+ // catalog optional {classify(key, isSubagent)} (lib/vendor-catalog.js);
161
+ // each answered entry then carries its group and vendor
152
162
  // }
153
163
  function createAgentRoster(deps) {
154
164
  var clock = typeof deps.clock === "function" ? deps.clock : Date.now;
@@ -157,6 +167,7 @@ function createAgentRoster(deps) {
157
167
 
158
168
  var timer = null;
159
169
  var lastWrite = Promise.resolve();
170
+ var avatarTail = null;
160
171
  var fullLogged = false;
161
172
 
162
173
  function changed() {
@@ -165,12 +176,18 @@ function createAgentRoster(deps) {
165
176
  catch (e) { console.error("[agent-roster] change hook failed:", e && e.message ? e.message : e); }
166
177
  }
167
178
 
179
+ // Resolves true when the write landed, false when it failed (logged). Never
180
+ // rejects, so a caller that does not wait cannot leave an unhandled rejection.
168
181
  function persistNow() {
169
182
  if (timer) { clearTimeout(timer); timer = null; }
170
183
  var body = { version: FILE_VERSION, agents: list() };
171
- lastWrite = Promise.resolve(deps.writeJson(deps.file, body)).catch(function (e) {
172
- console.error("[agent-roster] could not write " + deps.file + ":", e && e.message ? e.message : e);
173
- });
184
+ lastWrite = new Promise(function (resolve) { resolve(deps.writeJson(deps.file, body)); }).then(
185
+ function () { return true; },
186
+ function (e) {
187
+ console.error("[agent-roster] could not write " + deps.file + ":", e && e.message ? e.message : e);
188
+ return false;
189
+ }
190
+ );
174
191
  return lastWrite;
175
192
  }
176
193
 
@@ -195,21 +212,59 @@ function createAgentRoster(deps) {
195
212
  // existence would say where it was seen, so "unknown" and "not yours" are the
196
213
  // same answer. Avatar references name no project.
197
214
  function visibleEntry(caller, key) {
215
+ var decided = decideAccess(caller, key);
216
+ return decided ? decided.visible : null;
217
+ }
218
+
219
+ // The body of the access decision, shared by every answer that depends on it.
220
+ // Returns null (unknown key, or no readable place) or {visible, complete}:
221
+ // visible is visibleEntry's answer, complete is true when the caller may read
222
+ // every place the stored entry has. Callers use it instead of asking the
223
+ // access dependency again.
224
+ function decideAccess(caller, key) {
198
225
  var entry = typeof key === "string" ? agents.get(key) : null;
199
226
  if (!entry || typeof deps.mayReadProject !== "function") return null;
200
227
  var places = entry.places.filter(function (p) { return deps.mayReadProject(p.project, caller) === true; });
201
228
  if (places.length === 0) return null;
202
- return Object.assign(copyEntry(entry), { places: places.map(function (p) { return Object.assign({}, p); }) });
229
+ // Every field below reads only the places the caller may read: the latest
230
+ // sighting among them, the group and the vendor. The entry's firstSeen is
231
+ // never returned: the places kept are capped, so no caller-side rule can say
232
+ // that the first sighting was in a project the caller may read.
233
+ var lastSeen = places.reduce(function (latest, p) { return p.lastSeen > latest ? p.lastSeen : latest; }, places[0].lastSeen);
234
+ var visible = Object.assign(copyEntry(entry), classifyEntry(entry.key, places), {
235
+ lastSeen: lastSeen,
236
+ places: places.map(function (p) { return Object.assign({}, p); }),
237
+ });
238
+ delete visible.firstSeen;
239
+ return { visible: visible, complete: places.length === entry.places.length };
240
+ }
241
+
242
+ // Which Team view group an identity belongs in, read at answer time from the
243
+ // vendor catalog (deps.catalog.classify), never stored: {group, vendor}. An
244
+ // identity the catalog does not know, or no catalog, is a named agent. A
245
+ // helper must have been seen as a sub-agent, a model may arrive any way.
246
+ // Reads only the places the caller may read (the argument), never the stored
247
+ // entry, so a sighting in a project the caller cannot read changes nothing.
248
+ function classifyEntry(key, readablePlaces) {
249
+ var found = null;
250
+ if (deps.catalog && typeof deps.catalog.classify === "function") {
251
+ var isSubagent = readablePlaces.some(function (p) { return p.source === SOURCE.SUBAGENT; });
252
+ try { found = deps.catalog.classify(key, isSubagent); }
253
+ catch (e) { console.error("[agent-roster] classifying an identity failed:", e && e.message ? e.message : e); }
254
+ }
255
+ return found ? { group: found.group, vendor: found.vendor } : { group: GROUP.AGENT, vendor: null };
203
256
  }
204
257
 
205
- // The roster as one caller may see it, most recently seen first.
258
+ // The roster as one caller may see it, most recently seen first by the latest
259
+ // sighting in a place the caller may read (the stored lastSeen could be a
260
+ // sighting in a project the caller cannot read, and must not order the view).
206
261
  function listFor(caller) {
207
262
  var out = [];
208
263
  list().forEach(function (e) {
209
264
  var visible = visibleEntry(caller, e.key);
210
265
  if (visible) out.push(visible);
211
266
  });
212
- return out;
267
+ return out.sort(function (a, b) { return b.lastSeen - a.lastSeen || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0); });
213
268
  }
214
269
 
215
270
  function recordPlace(entry, sighting, now) {
@@ -258,16 +313,46 @@ function createAgentRoster(deps) {
258
313
  }
259
314
  }
260
315
 
261
- // Returns { ok: true, agent } or { ok: false, error }. A key the caller cannot
262
- // see (never seen, or seen only where the caller cannot read) gets the same
263
- // reply, and nothing changes. The reply carries the caller's own view.
264
- function setAvatar(caller, key, ref) {
265
- if (!visibleEntry(caller, key)) return { ok: false, error: NOT_SEEN };
316
+ // Resolves { ok: true, agent } or { ok: false, error }. The avatar is one
317
+ // global choice, so only a caller who may read every place the agent was seen
318
+ // may change it. A key the caller cannot see, or sees only in part, gets the
319
+ // reply of a key never seen, and nothing changes. A write that fails to
320
+ // persist is rolled back and answered with SAVE_FAILED; no nudge goes out for
321
+ // a change that did not stay. The reply carries the caller's own view. Calls
322
+ // are serialised: each waits for the earlier one to settle, success or failure,
323
+ // before it reads the avatar it may have to restore.
324
+ async function setAvatar(caller, key, ref) {
325
+ var earlier = avatarTail;
326
+ var release;
327
+ var mine = new Promise(function (resolve) { release = resolve; });
328
+ avatarTail = mine;
329
+ try {
330
+ if (earlier) await earlier;
331
+ return await applyAvatar(caller, key, ref);
332
+ } finally {
333
+ if (avatarTail === mine) avatarTail = null;
334
+ release();
335
+ }
336
+ }
337
+
338
+ async function applyAvatar(caller, key, ref) {
339
+ var decided = decideAccess(caller, key);
340
+ if (!decided || !decided.complete) return { ok: false, error: NOT_SEEN };
266
341
  var checked = validateAvatar(ref);
267
342
  if (!checked.ok) return checked;
268
343
  var entry = agents.get(key);
344
+ var previous = entry.avatar;
269
345
  entry.avatar = checked.avatar;
270
- persistNow();
346
+ var saved = await persistNow();
347
+ if (!saved) {
348
+ entry.avatar = previous;
349
+ // A persist a sighting started during the failed write snapshotted the
350
+ // rejected avatar and may still land. Writes to one path run in call
351
+ // order, so this one is last and the disk converges to memory. Now, not
352
+ // soon: the window in which the stale snapshot can land is already open.
353
+ persistNow();
354
+ return { ok: false, error: SAVE_FAILED };
355
+ }
271
356
  changed();
272
357
  return { ok: true, agent: visibleEntry(caller, key) };
273
358
  }
@@ -294,7 +379,19 @@ function createAgentRoster(deps) {
294
379
  return lastWrite;
295
380
  }
296
381
 
382
+ // What the vendors reported, [{vendor, models, helpers}]: model and helper
383
+ // names only, no project or session data, so it is the same for every caller.
384
+ function catalogSnapshot() {
385
+ if (!deps.catalog || typeof deps.catalog.snapshot !== "function") return [];
386
+ try { return deps.catalog.snapshot(); }
387
+ catch (e) {
388
+ console.error("[agent-roster] reading the vendor catalog failed:", e && e.message ? e.message : e);
389
+ return [];
390
+ }
391
+ }
392
+
297
393
  return {
394
+ catalogSnapshot: catalogSnapshot,
298
395
  observe: observe, visibleEntry: visibleEntry, listFor: listFor, setAvatar: setAvatar,
299
396
  renameCustomIcon: renameCustomIcon, list: list, flush: flush,
300
397
  };
@@ -305,7 +402,9 @@ module.exports = {
305
402
  validateAvatar: validateAvatar,
306
403
  senderKey: senderKey,
307
404
  NOT_SEEN: NOT_SEEN,
405
+ SAVE_FAILED: SAVE_FAILED,
308
406
  SOURCE: SOURCE,
407
+ GROUP: GROUP,
309
408
  MAX_AGENTS: MAX_AGENTS,
310
409
  MAX_PLACES: MAX_PLACES,
311
410
  MAX_KEY_LENGTH: MAX_KEY_LENGTH,
package/lib/agents.js CHANGED
@@ -118,43 +118,15 @@ function refresh(settingSources) {
118
118
  if (_refreshPromise) return _refreshPromise;
119
119
 
120
120
  _refreshPromise = (async function () {
121
- var sdk;
122
121
  try {
123
- sdk = await import("@anthropic-ai/claude-agent-sdk");
124
- } catch (e) {
125
- console.error("[agents] failed to import SDK:", e.message);
126
- _refreshPromise = null;
127
- return;
128
- }
129
-
130
- var sources = Array.isArray(settingSources) ? settingSources : ["user", "project", "local"];
131
- var abortController = new AbortController();
132
- var queryInstance = null;
133
- try {
134
- // Open a streaming-input session with an empty iterable. The SDK
135
- // initializes its subprocess and completes the handshake before
136
- // surfacing any events — supportedAgents() awaits that handshake.
137
- queryInstance = sdk.query({
138
- prompt: _emptyIterable(),
139
- options: {
140
- settingSources: sources,
141
- abortController: abortController,
142
- },
143
- });
144
-
145
- var agents = await queryInstance.supportedAgents();
146
- if (Array.isArray(agents)) {
147
- _cache = agents.map(agentInfoToEntry).filter(function (e) { return e.slug; });
122
+ var sources = Array.isArray(settingSources) ? settingSources : ["user", "project", "local"];
123
+ var found = await discoverAgentInfos(sources);
124
+ if (found) {
125
+ _cache = found.map(agentInfoToEntry).filter(function (e) { return e.slug; });
148
126
  console.log("[agents] discovered " + _cache.length + " agents via SDK");
149
- } else {
150
- console.warn("[agents] supportedAgents() returned non-array:", agents);
151
127
  }
152
- } catch (e) {
153
- console.error("[agents] SDK discovery failed:", (e && e.message) || e);
154
- // Keep last-known cache on failure.
128
+ // Keep last-known cache when discovery failed.
155
129
  } finally {
156
- // Abort the session subprocess — we don't need it anymore.
157
- try { abortController.abort(); } catch (e) { /* best-effort */ }
158
130
  _refreshPromise = null;
159
131
  }
160
132
  })();
@@ -162,6 +134,68 @@ function refresh(settingSources) {
162
134
  return _refreshPromise;
163
135
  }
164
136
 
137
+ // One SDK session that reads supportedAgents() under the given settingSources.
138
+ // Resolves the AgentInfo array, or null when the SDK could not be loaded, the
139
+ // call failed or it returned something else; never rejects. The session is
140
+ // aborted before returning.
141
+ async function discoverAgentInfos(sources) {
142
+ var sdk;
143
+ try {
144
+ sdk = await import("@anthropic-ai/claude-agent-sdk");
145
+ } catch (e) {
146
+ console.error("[agents] failed to import SDK:", e.message);
147
+ return null;
148
+ }
149
+
150
+ var abortController = new AbortController();
151
+ try {
152
+ // Open a streaming-input session with an empty iterable. The SDK
153
+ // initializes its subprocess and completes the handshake before
154
+ // surfacing any events — supportedAgents() awaits that handshake.
155
+ var queryInstance = sdk.query({
156
+ prompt: _emptyIterable(),
157
+ options: {
158
+ settingSources: sources,
159
+ abortController: abortController,
160
+ },
161
+ });
162
+
163
+ var agents = await queryInstance.supportedAgents();
164
+ if (Array.isArray(agents)) return agents;
165
+ console.warn("[agents] supportedAgents() returned non-array:", agents);
166
+ return null;
167
+ } catch (e) {
168
+ console.error("[agents] SDK discovery failed:", (e && e.message) || e);
169
+ return null;
170
+ } finally {
171
+ // Abort the session subprocess — we don't need it anymore.
172
+ try { abortController.abort(); } catch (e) { /* best-effort */ }
173
+ }
174
+ }
175
+
176
+ var _helpersPromise = null;
177
+
178
+ // The vendor's own built-in helpers: what supportedAgents() returns when no
179
+ // user, project or local settings are loaded (an empty settingSources). That
180
+ // set holds only what the vendor ships, never an operator's named agents.
181
+ // Reported to the vendor catalog as the Claude vendor's helpers; a failed call
182
+ // reports nothing and leaves the catalog as it was.
183
+ function refreshBuiltinHelpers(catalog) {
184
+ if (_helpersPromise) return _helpersPromise;
185
+ _helpersPromise = (async function () {
186
+ try {
187
+ var found = await discoverAgentInfos([]);
188
+ if (!found || !catalog) return;
189
+ catalog.report("claude", { helpers: found.map(function (info) {
190
+ return { name: info.name || "", description: info.description || "" };
191
+ }) });
192
+ } finally {
193
+ _helpersPromise = null;
194
+ }
195
+ })();
196
+ return _helpersPromise;
197
+ }
198
+
165
199
  // Return the last-known cached agent list. Synchronous; never throws.
166
200
  // Returns [] before the first refresh completes or if discovery failed.
167
201
  function getAll() {
@@ -249,5 +283,6 @@ module.exports = {
249
283
  readProjectAgents: readProjectAgents,
250
284
  // New SDK-backed surface:
251
285
  refresh: refresh,
286
+ refreshBuiltinHelpers: refreshBuiltinHelpers,
252
287
  getAll: getAll,
253
288
  };