dsh-agent-team-gui

Configuration

The bundle inserts this host row:

- id: agent-team-gui
  name: dsh-agent-team-gui
  config:
    defaultProvider: spawn
    defaultExecutionMode: serial
    defaultContextMode: spawn

Field	Type	Default	Meaning
defaultProvider	string	spawn	Registered dsh subagent provider used unless dispatch/context selection chooses another one.
defaultExecutionMode	serial | parallel	serial	Default member scheduling.
defaultContextMode	spawn | fork | chain	spawn	spawn starts fresh children; fork includes the parent's completed-turn prefix; chain passes each serial member's text to the next.

To override it for one profile, edit $DSH_HOME/profiles//cordis.patch.yml:

- id: agent-team-gui
  config:
    defaultProvider: fork
    defaultExecutionMode: parallel
    defaultContextMode: fork

dsh patch rows replace the complete config object; they are not deep-merged. Restate every field you need whenever overriding the row. chain is valid only with serial execution.

Agent records contain:

Field	Required	Meaning
name	yes	Display name.
systemPrompt	yes	Role/persona passed to the child agent.
provider	yes	Existing dsh provider route name.
model	yes	Existing model id for that provider.
maxTokens	no	Per-agent token cap.
toolScope.allow / toolScope.deny	no	dsh tool-name restrictions applied to that child.

Squad records contain:

Field	Required	Meaning
name	yes	Global display name used by Settings and conversation selectors.
members	yes	Unique agent IDs available to the squad.
collabNote	no	Collaboration guidance included in member prompts.
executionOrder	no	Fixed complete ordering of every member. Omit it for lead-model planning.
executionMode	no	Squad default: serial or parallel; falls back to plugin config.
contextMode	no	Squad default: spawn, fork, or serial-only chain; falls back to plugin config.

Squad records contain name, an optional collaboration note, a member list, optional executionOrder, and optional executionMode/contextMode defaults. An agent may appear in multiple squads. Settings → Teams edits these global records through a loopback-only host RPC. A fixed executionOrder must contain every member exactly once. With no fixed order, the lead model plans assignments and passes a complete memberOrder when dispatching. The plugin stores route names only; it does not store or copy provider secrets.

In-process service API

Plugin authors can also use the same registry in-process:

const agentId = await ctx.agentTeamGui.createAgent({
  name: 'Reviewer',
  systemPrompt: 'Review for correctness and cite concrete evidence.',
  provider: 'your-configured-provider',
  model: 'your-configured-model',
  toolScope: { allow: ['bash', 'str_replace_editor'] },
})

const squad = await ctx.agentTeamGui.createSquad({
  name: 'Release review',
  collabNote: 'Run independent checks, then consolidate findings.',
  members: [agentId],
})

The service also exposes get/list/update/delete methods for both record types, addMemberToSquad, removeMemberFromSquad, exportDefinitions/importDefinitions, and a programmatic dispatch method. Exact TypeScript signatures are exported by the package declarations.

Usage examples

Natural-language dispatch (available after a squad exists)

User: Give the release-review squad this task: inspect the patch for regressions.
      Have the reviewer check correctness and the test agent run focused tests in parallel.

Assistant: [calls dispatch_to_squad with squadId, task,
            assignments=[...], executionMode="parallel", contextMode="spawn"]

Assistant: The squad completed with two member results. The reviewer found ..., and the focused
           tests .... Any failed member is listed explicitly instead of being omitted.

The model selects dispatch_to_squad; the plugin does not parse the user's text with regular expressions. squadId accepts either the durable ID or an exact squad name (case-insensitive); if names are duplicated, use the durable ID. Tool arguments are squadId, task, optional assignments: [{ agentId, task }], optional executionMode, and optional contextMode. memberOrder is also optional when the squad has no fixed executionOrder; when supplied, it must be a complete, duplicate-free ordering of all squad members. A fixed squad order cannot be overridden per call. The tool renders the complete canonical JSON result—including each member's runId, childId, status, error, stop reason, and output—so the lead model can produce the final summary.

Conversation collaboration toggle

1. Start dsh --profile web and open Settings → Teams.
2. Create the agents. Choose each provider/model from the routes already configured in dsh; optionally enter max tokens and comma-separated allowed/denied tools.
3. Create a global squad, select its members, add an optional collaboration note, and optionally pin a fixed member order. Leave the order unset to let the model plan roles and ordering.
4. Open any conversation, select Release review in its squad selector, and enable squad collaboration.
5. Type the task in the normal composer and select Send. Disable the toggle to return that conversation to ordinary single-agent sends.

User types: Inspect this change and prepare a release recommendation.
Conversation control: Release review squad -> Collaboration on
User selects: Send

Assistant: [the selected squad collaborates using the current conversation as parent]
Assistant: The release-review squad recommends ... Reviewer: ... Test agent: ...

The selected squad is conversation-scoped and its mode is durable; both session modes and global agent/squad definitions survive restart. Deleting a selected squad automatically disables affected session modes. Sending does not require a second task box or a separate Dispatch button. Internally, a dynamic system prompt tells the lead model to call dispatch_to_squad once and summarize its result for the normal assistant response. This is a best-effort model instruction, not an API-level forced tool call; see Known limitations.

Export and import definitions

Settings → Teams can dump and restore the durable definitions as a JSON document.

• Export downloads agent-team-gui-.json containing { "format": "agent-team-gui/definitions", "version": 1, "agents": [...], "squads": [...] } — every record with its durable id, plus model routes (never API keys).
• Import reads such a file and applies it with merge semantics: document rows are upserted by id, rows already in the store that the document does not mention are kept, and a squad may reference an agent that already exists in the store. The whole document is validated first — shape, duplicate ids, model routes, and squad member references — so a rejected import writes nothing. (The durable writes themselves are not a single transaction: a storage failure mid-import can leave a partial apply.)

The same operations are available in-process as exportDefinitions() and importDefinitions(document, mode); mode is merge (default) or replace. replace makes the document the entire store, and then a squad may only reference agents present in the document.