dsh-agent-teams-meta

Readme

# dsh-agent-teams-meta

English | [简体中文](README.zh.md)

[![npm version](https://img.shields.io/npm/v/dsh-agent-teams-meta?color=blue)](https://www.npmjs.com/package/dsh-agent-teams-meta)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Build the team the task needs. Compose specialists freely, assign every member its own model route, and keep parallel work coordinated until the result is delivered.

A standalone multi-agent team plugin for DeepSeek Harness (DSH). It gives one lead AI a durable team of parallel members, each with its own provider and model route, private mailbox, assigned work, and independently tracked usage.

## What It Is For

Some tasks are better split into independent pieces: investigating a bug, reviewing a change, comparing approaches, or checking a release from several angles. `dsh-agent-teams-meta` lets a lead agent delegate that work to focused members, coordinate their progress, and collect the result in one place.

It is designed for real working sessions rather than a simulated chat room. Members run as durable DSH continuable agents, use the provider/model route assigned to them, and keep their own task context and mailbox across turns.

## Highlights

- **Parallel members with real routes** - Add members with a role and a configured provider/model pair. Different members can use different models in the same team.
- **Durable task coordination** - Create work with owners and dependencies. Members can only claim eligible work, and task status changes are validated and persisted.
- **Private, durable mailboxes** - The lead and members exchange direct messages without flooding unrelated conversations. Each participant can see only its own mailbox.
- **Live model switching** - Change a member's route whenever needed. The next model request uses the new route, while an in-flight request keeps its original provider/model attribution.
- **Useful failure reporting** - A member request failure is delivered to the lead as its raw error text in a normal next-turn message. Failures do not disappear into an opaque attachment or a generic status.
- **Configured-model catalog** - The plugin creates a workspace-local catalog of the providers and models that are currently configured in DSH, so agents know which routes are available before creating members.
- **Creation-time route checks** - Unknown providers, providers without a configured profile, and models outside an enumerable provider catalog are rejected before a member is started.
- **Per-route usage ledger** - Token use is recorded against the route that was active when each request began, even when a member changes routes later.
- **DSH Web visibility** - A read-only sidebar drawer shows team progress, members, tasks, routes, and phase without changing the team's source of truth.

## The Tool Family At A Glance

Everything goes through agent tools with the `teams_meta_*` prefix:

| Tool | Purpose |
| --- | --- |
| `teams_meta_create` | Create a team with a title and purpose |
| `teams_meta_add_member` | Add a member with a role and a configured provider/model |
| `teams_meta_remove_member` | Deactivate a member and cancel its open work |
| `teams_meta_create_task` | Define a task, optionally with an owner and dependencies |
| `teams_meta_claim_task` | Claim an eligible task (yourself only, after dependencies complete) |
| `teams_meta_update_task` | Move a task through its states and record a result |
| `teams_meta_send_message` | Send a durable direct message to a member or the lead |
| `teams_meta_route_switch` | Change a member's provider/model for the next request |
| `teams_meta_status` | Inspect members, tasks, routes, your mailbox, and usage |
| `teams_meta_close` | Archive the team after terminal work (or force-cancel) |
| `teams_meta_guide` | Return the full operating protocol on demand |

Agents receive the operating protocol automatically and can pull it again with `teams_meta_guide`.

## A Typical Flow

The lead creates a team, adds a specialist, gives it a concrete task, and sends the relevant context:

```text
teams_meta_create(title="Release audit", purpose="Review the release before publishing")
teams_meta_add_member(name="Reviewer", role="Find regressions", provider="deepseek-official", model="deepseek-v4-flash")
teams_meta_create_task(title="Review routing", owner="Reviewer")
teams_meta_send_message(to="Reviewer", body="Claim the routing task and report material findings.")
```

From there, members claim eligible tasks, report progress through their mailbox, and mark terminal results. The lead can inspect the team at any time, redirect a member to another configured route, or close the team when the work is complete.

## How It Works

Every member session carries a stable marker route:

```text
agent-teams-meta-route/<team-id>/<member-key>
```

At DSH's public request boundary, the plugin resolves that marker to the member's current real provider/model before DSH prepares the request. Normal DSH request headers, telemetry, and usage continue to use the real route, while route changes remain safe and predictable at request boundaries.

All plugin data remains in the workspace, separate from DSH's session store:

```text
.dsh-agent-teams-meta/
  routes.json        # current marker-to-route bindings
  requests.jsonl     # append-only route usage ledger
  model-catalog.md   # generated configured provider/model catalog
  teams/<team-id>/   # team snapshot and member mailboxes
```

Team snapshots use atomic replacement with retry for transient Windows file locks. Mailboxes and ledger entries are append-only. The state never stores prompts, model responses, credentials, or endpoint URLs.

## Requirements

- Node.js `^22.19.0` or `>=24`
- A DeepSeek Harness host with the Web profile (`dsh web`) and at least one configured LLM provider/model

## Install

The plugin is a standard npm package. Use either the DSH plugin command or pnpm directly inside the profile.

### Via the DSH plugin command

```sh
dsh plugin --profile web add dsh-agent-teams-meta
```

### Via pnpm

```sh
# from the DSH Web profile directory (e.g. ~/.dsh/profiles/web)
pnpm add dsh-agent-teams-meta
```

Then mount it through the profile's `cordis.patch.yml`:

```yaml
- insert:
    - id: agent-teams-meta
      name: 'dsh-agent-teams-meta'
      config:
        stateDir: .dsh-agent-teams-meta
        markerProvider: agent-teams-meta-route
```

Restart DSH after installing or upgrading a host-side plugin.

### Build from source

Clone the repository, install dependencies, and build the plugin locally:

```sh
git clone https://github.com/YshuY/dsh-agent-teams-meta.git
cd dsh-agent-teams-meta
pnpm install
pnpm build
```

Then link the built package into the DSH Web profile:

```sh
# from the DSH Web profile directory
pnpm add link:E:/path/to/dsh-agent-teams-meta
```

A `link:` install shares the live source tree, so every rebuild is picked up on the next DSH restart.

### Local development (link install)

For active development, the linked install above is the same workflow: edit the source, run `pnpm build`, then restart DSH to load the changes.

## Optional Configuration

The plugin works out of the box. If you want to customize the state directory or route marker, mount it through a `cordis.patch.yml`:

```yaml
- insert:
    - id: agent-teams-meta
      name: 'dsh-agent-teams-meta'
      config:
        stateDir: .dsh-agent-teams-meta
        markerProvider: agent-teams-meta-route
```

Both keys are optional; these are the defaults.

## FAQ

**Can members use different models?**
Yes. Each member is added with its own provider/model route, and the lead can switch a member to any other configured route at any time.

**Where does the data live?**
Everything is under `.dsh-agent-teams-meta/` in the workspace. Team snapshots are replaced atomically; mailboxes and the usage ledger are append-only. No prompts, responses, credentials, or endpoint URLs are stored.

## Web Panel

A read-only drawer in the DSH Web sidebar shows the current team snapshot: task progress, members, routes, and phase. All changes still go through the `teams_meta_*` tools.

![Meta team panel in the DSH Web sidebar](assets/team-panel.png)

## Development

```sh
pnpm install
pnpm verify
```

`pnpm verify` runs type checking, the production build, unit tests, and an integration check for durable member routing.

## More Detail

The repository also includes focused technical notes:

- [Architecture](docs/architecture.md)
- [Operations](docs/operations.md)
- [Verification](docs/verification.md)

## License

MIT