dsh-subagent-hub 0.0.0-stage → 0.10.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ccsert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ccsert/dsh-subagent-hub/v0.10.2/docs/assets/hero.webp" alt="Subagent Hub — Named roles. Clear routes. Visible models." width="100%">
+</p>
 
-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.
+<p align="center">
+  <a href="https://github.com/ccsert/dsh-subagent-hub/releases/tag/v0.10.2"><img src="https://img.shields.io/badge/version-0.10.2-66c8ab" alt="Version 0.10.2"></a>
+  <a href="https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  <a href="https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/install.md"><img src="https://img.shields.io/badge/DSH_Desktop-0.12.1-7087ad" alt="Tested with DSH Desktop 0.12.1"></a>
+  <a href="https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/CONTRIBUTING.md"><img src="https://img.shields.io/badge/verified-102_unit_%2B_31_runtime-66c8ab" alt="102 unit tests and 31 runtime assertions verified"></a>
+</p>
+
+<p align="center"><a href="https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/README.md">简体中文</a> · <b>English</b></p>
+
+# Subagent Hub
+
+**Roles, model selection context, and route boundaries for official DeepSeek Harness subagents.** Give the main agent useful reviewer, tester, or research roles; manage allowed models in Settings; inspect the most recent model request from a child conversation.
+
+Uses official `subagent` / `subagent_fork` dispatch, Agent Presets, and conversation UI. Keep your existing main-agent preset.
+
+[Install](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/install.md) · [Download a release](https://github.com/ccsert/dsh-subagent-hub/releases/latest) · [Configuration example](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/examples/subagent-hub.yml) · [Changelog](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/CHANGELOG.md) · [Contribute](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/CONTRIBUTING.md)
+
+## Features
+
+| Feature | Behavior |
+|---|---|
+| **Named roles** | Register official `hub-agent-<id>` presets and dispatch with `agent_preset` |
+| **Model selection catalog** | Provide configured routes, capabilities, purposes, and role instructions to the main agent |
+| **Route guard** | Check the global child routes before subagent, fork, and Team creation; named roles can narrow that range further |
+| **Per-session concurrency** | Limit child agents in each parent session, alongside DSH's global capacity |
+| **Native settings form** | Edit models, roles, tags, and management options in **Settings → Subagent Hub** |
+| **Request model visibility** | Read the latest provider/model from the child header; expand for full IDs and recorded reasoning effort |
+
+## Screenshots
+
+**Models and named agents**
+
+![Actual configuration component with demo models and named agents](https://raw.githubusercontent.com/ccsert/dsh-subagent-hub/v0.10.2/docs/assets/settings.webp)
+
+**The latest child request**
+
+![Child header with full provider, model ID and reasoning effort](https://raw.githubusercontent.com/ccsert/dsh-subagent-hub/v0.10.2/docs/assets/model-badge.webp)
+
+These are the actual plugin components rendered with demo data. They contain no user profile, private conversation, or credentials. See [screenshot provenance](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/screenshots.md) for full-size and narrow views. The Hero was generated with [dsh-image-gen](https://github.com/shanliuling/dsh-image-gen).
+
+## Quick start
+
+Tested with **DSH Desktop 0.12.1 / `@deepseek-ai/dsh` 0.2.1-rc.2**. Configure a working model provider in DSH first.
+
+1. Download `dsh-subagent-hub-0.10.2.tgz` from [Releases](https://github.com/ccsert/dsh-subagent-hub/releases/latest).
+2. Install it from the target profile directory:
+
+   ```bash
+   pnpm add /absolute/path/to/dsh-subagent-hub-0.10.2.tgz
+   ```
+
+3. **Append** `"dsh-subagent-hub"` to `dsh.profile.bundles` in that profile's package manifest. Preserve existing bundles and restart DSH to load the plugin code.
+4. Open **Settings → Subagent Hub**, select models already available in your DSH, and add a role. Enable **Manage the official delegation settings** if you want Hub to synchronize the official allowlists. Save, then start a new conversation.
+
+Git checkout installation, profile locations, upgrades, and removal are covered in the [installation guide](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/install.md). The package is published as [dsh-subagent-hub](https://www.npmjs.com/package/dsh-subagent-hub); fixed GitHub release archives are also available. The Team/inheritance guard requires 0.10.2 or newer.
+
+## Minimal configuration
+
+The settings form and profile patch edit the same configuration. The provider/model below must already be available in your DSH:
+
+```yaml
+- id: subagent-hub
+  config:
+    maxConcurrent: 4
+    manageOfficialSettings: true
+    routes:
+      - id: flash
+        provider: deepseek-official
+        model: deepseek-flash
+        tags: [fast, cheap]
+    agents:
+      - id: reviewer
+        description: Reviews changes and reports concrete findings
+        instructions: Read the diff, report actionable findings, and do not edit files.
+        routes: [flash]
+```
+
+Try: **“Use reviewer to review the current changes. Report concrete findings without editing files.”**
+
+The main agent selects a role based on the task and catalog. When the official tool exposes the parameter, `agent_preset: hub-agent-reviewer` selects this role. The route guard checks the delegation before dispatch.
+
+## Behavior to keep in mind
+
+- **Team context selects history.** In the supported runtime, fresh and fork both inherit the Lead model and have no model-selection input. For a specific child model, use a `subagent` tool whose actual schema exposes model selection. See [Team model routing](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/team-model-routing.md).
+- **Global routes also guard inheritance.** A nonempty `routes` list bounds all three creation tools; out-of-list or unconfirmed models are refused. An empty list retains native inheritance. Existing members and later request rewrites are outside this creation check.
+- **Tags guide decisions.** Tags such as `fast`, `reasoning`, or `free` are maintained by you. Use a role's `routes` for a hard route boundary. Tags do not verify pricing or implement automatic fallback.
+- **The guard runs before dispatch.** Model rewrites performed by other plugins during a later child request are outside this guard. Check those plugins when combining route policies.
+- **Fork follows official capabilities.** The target fork provider does not support an independent `agent_preset`; named roles use `subagent`.
+- **Managed settings are opt-in.** `manageOfficialSettings` defaults to `false`. Enabling it synchronizes official allowlists. Disabling it stops syncing and retains settings already written.
+- **Existing conversations keep their tool schema.** Saved configuration is live; use a new conversation for newly added roles or tool parameters. Plugin code upgrades require a DSH restart.
+- **The model badge shows request history.** `lastUsed` identifies the latest request; a different `next` selection is shown separately. A ready empty history says “No request yet”; unavailable data says “Unconfirmed.” A request record does not establish success or billing, and forked history may include inherited requests.
+
+## Development (repository checkout)
+
+```bash
+npm ci
+npm run test:unit       # no model account required
+npm run docs:check      # local documentation links, assets, and metadata
+bash test.sh           # real DSH integration in a temporary DSH_HOME
+npm run pack:check     # inspect the distributable archive
+```
+
+This release is verified by **87 unit tests and 23 real-runtime assertions**. Integration uses scripted model streams and makes no external model calls. CI runs unit, documentation, and package checks. See the [settings acceptance record](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/ui-acceptance.md) and [model badge acceptance record](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/model-badge-acceptance.md) for scope and limitations. [Team routing verification](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/team-model-routing.md) covers the new creation checks.
+
+Issues and PRs are welcome. Read [CONTRIBUTING](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/CONTRIBUTING.md), the [design notes](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/design.md), and the [release guide](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/docs/releasing.md). The previous v0.3.0 architecture remains available at its tag.
+
+[MIT License](https://github.com/ccsert/dsh-subagent-hub/blob/v0.10.2/LICENSE) · Maintained by [ccsert](https://github.com/ccsert)

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-subagent-hub: one Host row plus one browser config card. It reads `routes` and `agents`
+# (both live-editable from that card on the official Plugins page), registers each agent as an
+# Agent Preset, and adds a system-prompt catalog plus a route guard to the official delegation
+# tools. It does not replace them.
+#
+#   - id: subagent-hub
+#     config:
+#       routes:                       # exact child models; also the official allowedModels list
+#         - { id: flash, provider: <provider>, model: <model>, tags: [fast], note: <label> }
+#         - { id: pro,   provider: <provider>, model: <model>, tags: [reasoning] }
+#       agents:                       # each becomes preset `hub-agent-<id>`
+#         - { id: reviewer, description: Reviews diffs, instructions: '...', routes: [pro] }
+#       maxConcurrent: 4              # children running at once per session; 0 = unlimited
+#       manageOfficialSettings: false # true == this plugin writes the official allowlists
+- insert:
+    - id: subagent-hub
+      name: dsh-subagent-hub

package/lib/catalog.js

@@ -0,0 +1,54 @@
+// Resolve the plugin configuration into the runtime catalog: indexed routes, named agents with
+// stable official preset ids, and the problems that made a row unusable. Pure and testable;
+// the Host service only registers what this returns.
+
+import { normalizeDefinition } from './definitions.js'
+import { indexRoutes, knownTags } from './router.js'
+
+/** Prefix of every Agent Preset this plugin registers. Also the marker used to own allowlist entries. */
+export const AGENT_PRESET_PREFIX = 'hub-agent-'
+
+/** Stable official preset id of one named agent. No fingerprint: the id is written into the profile. */
+export function presetIdOf(agentId) {
+  return `${AGENT_PRESET_PREFIX}${agentId}`
+}
+
+/**
+ * @param {{ routes: Array<Record<string, unknown>>, agents: Array<Record<string, unknown>> }} config
+ * @returns {{
+ *   routes: Map<string, any>,
+ *   agents: any[],
+ *   byPreset: Map<string, any>,
+ *   tags: string[],
+ *   problems: string[],
+ * }}
+ */
+export function buildCatalog(config) {
+  const { routes, problems: routeProblems } = indexRoutes(config.routes ?? [])
+  const problems = [...routeProblems.map(problem => `routes: ${problem}`)]
+  const agents = []
+  const byPreset = new Map()
+  for (const [index, raw] of (config.agents ?? []).entries()) {
+    let agent
+    try {
+      agent = normalizeDefinition(raw, `agents[${index}]`)
+    } catch (error) {
+      problems.push(String(error?.message ?? error))
+      continue
+    }
+    const missing = (agent.routes ?? []).filter(id => !routes.has(id))
+    if (missing.length > 0) {
+      problems.push(`agent "${agent.id}" names unknown route${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`)
+      continue
+    }
+    const presetId = presetIdOf(agent.id)
+    if (byPreset.has(presetId)) {
+      problems.push(`duplicate agent id "${agent.id}"`)
+      continue
+    }
+    const entry = { ...agent, presetId }
+    agents.push(entry)
+    byPreset.set(presetId, entry)
+  }
+  return { routes, agents, byPreset, tags: knownTags(routes), problems }
+}