@monster-orange/den 0.4.26 → 0.4.28

package/CHANGELOG.md

@@ -4,6 +4,94 @@ 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
+
+- **Connect to Hub (HUB-1.7).** Settings › Agents › Hub has **Connect**:
+  type Hub's address, sign in on Hub, pick the company and approve this
+  install, and you come back connected. Nobody copies a token or edits
+  config. Den uses PKCE and a single-use state; the token goes to the
+  install's own secrets store (1Password or Doppler), else to a 0600
+  file in Den's state dir, and never to a page, log or command line.
+  **Disconnect** revokes it on Hub first. A token Hub no longer accepts
+  shows **Reconnect**; a role that may no longer connect says to ask a
+  Hub admin. The row shows the company (a link), your role, who signed
+  in and this install. Doctor's Hub row names the company and role.
+- Agents' Hub MCP server uses Hub's own `mcp_url` from Connect, and
+  sends `X-Den-Agent-Id` (the agent's stable id) for attribution.
+
+### Changed
+
+- Hub status comes from Hub's `GET /connect/whoami` (it was the
+  `hub_whoami` MCP tool).
+
+### Fixed
+
+- **Saving to 1Password never makes a second item.** A save created a
+  new item whenever reading the old one failed, even for a timeout, so a
+  slow `op` could leave two items with one title (which `op` then
+  refuses). It now creates only when `op` says the item isn't there, and
+  otherwise shows `op`'s reason. A failed create shows create's own
+  reason (say, a vault that isn't available), not "isn't an item".
+- `op`'s `[ERROR] <date> <time>` prefix is gone from the messages Den
+  shows.
+- After the admin password is saved to the install's store, the note
+  says so: "Admin password kept for this session and saved to <store>".
+
+### Migrations
+
+- None. A `hub.token` set by hand keeps working. `hub.token` may now
+  also be a source (`file:`, `keychain:`, `env:`), and `hub.mcp_url` is
+  new and optional.
+
 ## [0.4.26] - 2026-11-10
 
 ### Security

package/docs/distributions.md

@@ -913,9 +913,63 @@ later plugins.
 
 ## Hub
 
-With `hub.url` set, every agent Den launches gets Hub's tools (HUB-1.5):
-it can search Hub and publish docs and mocks there. Without `hub.url`,
-nothing changes and nothing about Hub shows.
+Connect an install to your company's Hub and every agent Den launches
+gets Hub's tools: it can search Hub and publish docs and mocks there.
+Without it, nothing about agents changes.
+
+### Connect to Hub (HUB-1.7)
+
+Settings › Agents › Hub: type Hub's address (or keep the one the
+distribution set in `hub.url`) and press **Connect**. Hub opens; sign
+in, pick the company and approve this install. Hub sends you back to
+Settings, connected. Nobody copies a token or edits config.
+
+- Den makes a PKCE verifier (S256) and a single-use state and keeps both
+  in memory for 10 minutes. Hub's answer comes back to
+  `<this Den>/hub/callback`, which trades the one-time code for the
+  install's token server to server (`POST <hub>/connect/token`). A
+  replayed or old state changes nothing.
+- `/hub/callback` needs no sign-in: the session cookie is SameSite
+  Strict, so Hub's redirect doesn't carry it. The state this server
+  issued to a signed-in Connect, and the verifier only it holds, are
+  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), 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`
+  (field `token`), or a Doppler key `<PREFIX>_HUB_TOKEN`. Otherwise Den
+  keeps it in `<state dir>/hub/token` (mode 0600, folder 0700). It goes
+  to the store on stdin or into the file, never in a command line, and
+  never to a page, a log or an API answer. If it can't be kept, Den
+  revokes it on Hub at once.
+- 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** 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
+  token still works on Hub until an admin revokes the install.
+- 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
+
+A distribution can preset Hub's address, or set everything by hand:
 
 ```yaml
 # config/local/user.yml (or the org config; user.yml wins)
@@ -923,20 +977,27 @@ hub:
   url: https://hub.example.com
   token: { vault: Private, item: Acme Hub, field: token }
   # or the name of a secrets.refs entry: token: hub_install
+  # or a source: token: "file:/path/to/token" (also keychain:, env:)
+  mcp_url: https://hub.example.com/mcp # default: <url>/mcp
   allow_tools: true # the default: agents use Hub's tools without asking
 ```
 
 - `hub.url` must be https. Plain http works only to this machine
-  (`localhost`, `*.localhost`).
-- `hub.token` is this install's Hub token (`hubi_…`, one per install,
-  made in Hub), as a ref in this install's own secrets store
-  (`secrets.provider`). Den never assumes a vault, item or field for it.
+  (`localhost`, `127.0.0.1`, `*.localhost`).
+- `hub.token` is this install's Hub token (one per install), as a ref in
+  this install's own secrets store (`secrets.provider`) or a source. Den
+  never assumes a vault, item or field for it.
+
+### What agents get
+
 - Each agent's MCP config gets a server named `hub`: Streamable HTTP at
-  `<hub.url>/mcp`, with `Authorization: Bearer <token>` and four plain
-  headers naming the caller: `X-Den-Agent` (its name), `X-Den-Session`
-  (a new opaque id per launch), `X-Den-Workspace` and `X-Den-Repos` (the
-  workspace's repos, `owner/repo`, comma-separated). Hub sets the team
-  from the token and the project from the repos.
+  `hub.mcp_url` (default `<hub.url>/mcp`), with
+  `Authorization: Bearer <token>` and plain headers naming the caller:
+  `X-Den-Agent` (its name), `X-Den-Agent-Id` (its stable id, which Hub
+  keys attribution on), `X-Den-Session` (a new opaque id per launch),
+  `X-Den-Workspace` and `X-Den-Repos` (the workspace's repos,
+  `owner/repo`, comma-separated). Hub sets the company from the token
+  and the project from the repos.
 - Its prompt gets one line: "You can search Hub and publish docs and
   mocks there with the hub\_\* tools; your team and project are set from
   this Den install."
@@ -944,18 +1005,22 @@ hub:
   in a command line, a record, a log, a page or an API answer.
 - `hub.allow_tools` (default `true`): agents use Hub's tools without
   asking (Den allows `mcp__hub` for every agent it launches). The token
-  limits writes to this install's team, and Hub keeps every version. Set
-  it to `false` and Hub's tools ask before they run, like any tool. An
-  explicit deny in the install's own Claude Code permissions still wins.
-  Settings › Agents › Hub has the checkbox (it saves to
+  limits writes to this install's company, and Hub keeps every version.
+  Set it to `false` and Hub's tools ask before they run, like any tool.
+  An explicit deny in the install's own Claude Code permissions still
+  wins. Settings › Agents › Hub has the checkbox (it saves to
   `config/local/user.yml`).
 - A Hub that is down, or a token that can't be read, never stops an
   agent: it starts without Hub.
 
-Settings › Agents › Hub shows the URL, connected or not, the team and
-this install's label (from Hub's whoami tool), or why it can't connect.
-`GET /api/hub` answers the same. `<cli> doctor` has a Hub row: ✓ when
-connected, ⚠ with the reason when not. A Hub that is down never fails
+### Status
+
+Settings › Agents › Hub shows Hub's address, connected or not, the
+company (a link to it on Hub), your role, who signed in and this
+install's label (from `GET <hub>/connect/whoami`), or why it can't
+connect. `GET /api/hub` answers the same (never the token). `<cli>
+doctor` has a Hub row: ✓ when connected, ⚠ with the reason when not,
+and where to Connect or Reconnect. A Hub that is down never fails
 doctor.
 
 ## doctor
@@ -2966,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.26",
+  "version": "0.4.28",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {