@monster-orange/den 0.4.27 → 0.4.28

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.28] - 2026-11-10
+
+### Added
+
+- **An agent's helpers (D32).** When an agent starts helpers of its own
+  (Claude Code's Agent and Workflow subagents), Den shows them, read-only:
+  under the agent's row on the Agents tab, in a **Helpers (n)** list from
+  the pane's bar, and as a count on the rail's Agents item on every page.
+  Click one to read its transcript: what it was asked, its answers, and
+  its tool calls in a few words. Den can't stop or steer a helper, and
+  says so; to change what one does, tell the agent. Helpers from the
+  agent's earlier conversations are folded under "Earlier (n)". A
+  helper's own helpers sit under it, and a running one is listed first,
+  with the helper it belongs to. Also
+  `<cli> agents helpers <id> [<helper>]` (`--all`, `--limit`, `--json`),
+  the MCP tool `agent_helpers`, and the routes `GET
+  /api/workspaces/<ws>/agents/<id>/helpers[/<helper>]` and `GET
+  /api/sessions/helpers`.
+- **Hub in the rail.** Once this install is connected, the rail has a
+  **Hub ↗** link above Settings: the company's page on Hub, in a new tab,
+  with a count of the threads waiting on you. When Hub rejects the token
+  or forbids the role, the link is greyed and goes to Settings › Hub.
+- **Connect sends `den_url`:** this Den's edge address, when it has one
+  (https, else `http://<name>.localhost`), so Hub can link back to it.
+- **`agents.helpers` settings:** `active_minutes` (default 10: no activity
+  this long and not known done shows idle) and `collapse_done_minutes`
+  (default 30: done helpers fold away after this).
+
+### Changed
+
+- **Connect to Hub from a `.localhost` address.** An edge on this machine
+  reached over http (`http://<name>.localhost`) now counts as this
+  machine, like localhost.
+- **Disconnect asks first,** saying it revokes this Den's Hub key on Hub
+  and that agents lose Hub until you Connect again.
+
+### Fixed
+
+- The Agents list no longer drops keyboard focus every few seconds: its
+  refresh kept redrawing it. Focus stays on the row or button it was on.
+
+### Migrations
+
+- `helpers` under `agents:` is now a reserved key (D32's settings). A
+  distribution with an agent whose id is `helpers` must rename it.
+  Nothing else: `agents.helpers` is optional.
+
 ## [0.4.27] - 2026-11-10
 
 ### Added

package/docs/distributions.md

@@ -935,7 +935,12 @@ Settings, connected. Nobody copies a token or edits config.
   what protect it. It then moves on to Settings by script, which carries
   the cookie again.
 - Hub can only send the person back to https or to this machine, so
-  open Den over https (its edge address) or on localhost to Connect.
+  open Den over https (its edge address), on localhost, or on a
+  `<name>.localhost` address (an edge on this machine over http; RFC 6761
+  keeps it on this machine) to Connect.
+- When this Den has an edge address, Connect sends it as `den_url`:
+  its https one, else an `http://<name>.localhost` one. Hub links back to Den with it when the browser came over
+  loopback. A Reconnect sends it again.
 - This install's label on Hub is `<cli> on <machine>`.
 - The token is the install's (SEC-0), kept in the install's own secrets
   store when it keeps secrets: a 1Password item `<Product> Hub token`
@@ -947,7 +952,8 @@ Settings, connected. Nobody copies a token or edits config.
 - Connect writes `hub.url` (Hub's own address), `hub.token` (the store
   ref, or `file:<path>`) and `hub.mcp_url` (Hub's MCP address, as given)
   to `config/local/user.yml`.
-- **Disconnect** revokes the token on Hub (`POST <hub>/connect/revoke`),
+- **Disconnect** asks first: "This revokes this Den's Hub key on Hub.
+  Agents lose Hub until you Connect again." Then it revokes the token on Hub (`POST <hub>/connect/revoke`),
   then removes it here and clears `hub.token` and `hub.mcp_url`;
   `hub.url` stays, so Connect is one click. If Hub can't be reached,
   nothing is removed; **Remove it here anyway** removes it, and says the
@@ -955,6 +961,11 @@ Settings, connected. Nobody copies a token or edits config.
 - A token Hub no longer accepts (revoked, or replaced by a newer
   connect) shows **Reconnect**. A role that may no longer connect Den
   installs says to ask a Hub admin; Den never retries it.
+- Once connected, the rail has a **Hub ↗** link above Settings. It opens
+  the company's page on Hub in a new tab, with the company in its tooltip
+  and a count of the threads waiting on you (Hub's `unread`). A token Hub
+  rejects, or a role it forbids, greys it, and it goes to Settings › Hub
+  instead. Den looks at Hub for it once a minute while a page shows.
 
 ### Config
 
@@ -3020,6 +3031,66 @@ The pane's header and the workspace's heading in the list link to the
 Workspaces page focused on that workspace (`/local-dev?ws=<ws>`), and ⌘K
 has "Go to workspace <ws>" for each workspace with agents.
 
+### Helpers: what an agent started in its own session
+
+An agent can start helpers of its own: Claude Code's Agent and Workflow
+subagents (D32). They run inside the agent's session, so Den shows them
+but can't stop or steer them. To change what they do, tell the agent.
+
+Where they show:
+
+- **The Agents tab.** Under a running or stopped agent's row, its recent
+  helpers, running ones first, each with what it was asked to do, its
+  state and when. "All helpers (n)" opens the full list. Done, failed and
+  stopped helpers fold away after a while (`collapse_done_minutes`).
+- **A pane's bar.** **Helpers (n)** opens the list, with a count while any
+  run. Helpers from the agent's earlier conversations (before a relaunch)
+  are folded under "Earlier (n)".
+- **A helper's transcript.** Click a helper: what it was asked, its
+  answers, and its tool calls in a few words, the newest at the bottom.
+  Never its thinking.
+- **The rail.** The Agents item counts the helpers running now, on every
+  page.
+
+A helper's state comes from Claude Code's files, best evidence first: the
+person stopped it, its workflow said, the agent was told it ended, its
+result is in the agent's transcript, its own files say it finished, its
+last answer went quiet, or recent activity. A helper with no activity for
+`active_minutes` that isn't known to be done shows **idle**. When the
+agent isn't running, none of its helpers are. Hover a state to see which
+evidence it came from.
+
+From the CLI and MCP:
+
+```sh
+<cli> agents helpers <id>              # this conversation's helpers
+<cli> agents helpers <id> --all        # earlier conversations' too
+<cli> agents helpers <id> <helper>     # one helper's transcript
+<cli> agents helpers <id> <helper> --limit 50 --json
+```
+
+The MCP tool `agent_helpers` reads the same, in the agent's own workspace
+or one it is granted. The routes are `GET
+/api/workspaces/<ws>/agents/<id>/helpers[/<helper>]` and `GET
+/api/sessions/helpers` (the running count). All of them only read.
+
+Settings, under `agents.helpers` in the org config:
+
+```yaml
+agents:
+  helpers:
+    active_minutes: 10 # no activity this long, not known done: idle
+    collapse_done_minutes: 30 # done helpers fold away after this
+```
+
+| Key                     | Values                     | Default |
+| ----------------------- | -------------------------- | ------- |
+| `active_minutes`        | minutes, above 0 to 100000 | 10      |
+| `collapse_done_minutes` | minutes, above 0 to 100000 | 30      |
+
+A runtime other than Claude Code shows no helpers: Den says it can't tell
+which helpers that agent started.
+
 ### Stopped agents: Resume, Start fresh, Remove
 
 An agent that stops stays in the list, below the running ones (AG-14, the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {