dsh-consult

Readme

# dsh-consult

[![npm version](https://img.shields.io/npm/v/dsh-consult?logo=npm)](https://www.npmjs.com/package/dsh-consult)
[![CI](https://github.com/DK-Zhu/dsh-consult/actions/workflows/ci.yml/badge.svg)](https://github.com/DK-Zhu/dsh-consult/actions/workflows/ci.yml)
[![license](https://img.shields.io/github/license/DK-Zhu/dsh-consult)](LICENSE)

English · [简体中文](README.zh-CN.md)

> **Bring a second opinion to every decision that matters.**

`dsh-consult` gives [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) an explicit,
evidence-first review checkpoint. One agent does the work. When a decision deserves more scrutiny,
2–5 independently configured models receive the same brief and answer the same question. The main
agent compares their anonymous opinions and remains accountable for the call.

```text
/consult Finish the implementation and tests, then ask the panel whether this is ready to ship.
```

No background committee. No automatic model spend. No second team competing to edit the workspace.

## Agent teams scale labor. dsh-consult diversifies judgment.

An agent team is useful when a task benefits from more hands: split the work, assign different roles,
explore several areas, and combine the deliverables. As a mental model, it is one capable operator
wearing several hats.

Consultation addresses a different problem. It is closer to inviting different reviewers into the
same room, handing each of them the same evidence, and asking one carefully framed question. They do
not divide the task or converge through discussion. The value comes from seeing where independent
models agree, where they disagree, and what one model noticed that another did not.

| | Agent team / subagents | dsh-consult |
| --- | --- | --- |
| Optimizes for | Execution capacity | Decision quality |
| Work allocation | Different roles or subtasks | The same question for every model |
| Context | Gathered per assignment | One shared, selected evidence packet |
| Tools | Usually available | No tools, history, or workspace access |
| Output | Work products to merge | Independent opinions to assess |
| Spend | Grows throughout execution | Occurs only at an explicit checkpoint |

This distinction matters because execution is often the predictable part once a direction is chosen.
A strong main agent can implement, test, and verify a settled plan end to end. Keeping a committee of
tool-using agents active throughout that process adds coordination, context, and tool-call cost even
when there is little useful disagreement left. `dsh-consult` reserves model diversity for the moment
when diversity is valuable, then hands ownership back to one agent.

## Good moments for a second opinion

Use consultation for decisions with leverage or uncertainty:

- choosing between plausible architectures;
- reviewing a security, privacy, or data-retention boundary;
- challenging a migration or rollback plan;
- checking release readiness after the implementation is complete;
- examining subtle failure modes and recovery behavior;
- balancing performance, maintainability, compatibility, and user experience;
- testing whether a conclusion is robust or merely one model's preference.

Routine edits, obvious fixes, and already-settled execution usually do not need a panel. Consultation
works best as a deliberate, high-value checkpoint—not a tax on every turn.

## A controlled review loop

```mermaid
flowchart LR
    U["User requests /consult"] --> A[Main agent investigates and verifies]
    A --> P[One question + selected evidence]
    P --> C1[Model A reviews]
    P --> C2[Model B reviews]
    P --> CN[Models C–E review]
    C1 --> S[Main agent compares and synthesizes]
    C2 --> S
    CN --> S
    S --> R[Final recommendation]
```

The loop is intentionally opinionated:

- **Opt-in only.** External consultants are never called without `/consult <task>`.
- **Work before review.** The main agent investigates, implements, and validates before preparing the
  panel brief.
- **A level playing field.** Every consultant receives the same system prompt, question, constraints,
  and evidence.
- **Independent answers.** Calls run in parallel; consultants cannot debate, vote, or see one another.
- **Anonymous synthesis.** The main model sees stable labels such as `Consultant A`, not provider or
  model brands.
- **One accountable owner.** Advice informs the decision; it never replaces the main agent's judgment.
- **Bounded cost.** The operator controls panel size, routes, timeouts, generation limits, and accepted
  opinion size.

## Quick start

You need Node.js `>=22.19.0`, a compatible DeepSeek Harness release, and at least two DSH model
configurations, each identified by a `provider` and `model`.

### 1. Install the bundle

```sh
dsh plugin --profile web add dsh-consult
```

If you run DSH through a package runner:

```sh
pnpm dlx @deepseek-ai/dsh plugin --profile web add dsh-consult
```

### 2. Choose the panel

The bundle starts dormant and makes no model calls. Add this minimal override to
`~/.dsh/profiles/web/cordis.patch.yml`, or the equivalent profile under `DSH_HOME`:

```yaml
- id: consult
  config:
    consultants:
      - provider: "<provider-id-a>"
        model: "<model-id-a>"
      - provider: "<provider-id-b>"
        model: "<model-id-b>"
```

Replace each value in angle brackets with its DSH identifier: `provider` names the model service and
`model` names a model available through that service. Credentials stay in DSH settings and credential
stores; `dsh-consult` neither reads nor saves API keys. The two provider IDs may be the same—for
example, you can select two different models from one service. Only the complete `provider` + `model`
pair must be unique. The example is the smallest valid panel; add more entries in the same form for a
total of up to five consultants. Everything else is optional and falls back to a documented default;
add those settings only when you want to tune them. See [Configuration](docs/configuration.md) for the
complete reference.

Verify the composed profile and start DSH:

```sh
dsh --profile web --dump-config
dsh web
```

### 3. Ask at the decision boundary

```text
/consult Review the cache invalidation redesign. Inspect the implementation and tests first, then decide whether it is ready to ship.
```

The main agent continues normal workspace work and calls `consult` once the evidence is ready. A
pending request can be cancelled with `/consult off`.

## What remains under your control

- You select 2–5 model configurations and may tune reasoning effort for each one.
- Consultants run concurrently, so latency is normally set by the slowest route rather than the sum.
- A fully successful panel returns `complete`; one or more valid opinions return `partial`.
- Route identity, raw provider failures, usage, and timing remain in model-hidden diagnostic events.
- Durable intent and delivery state prevent recovery from silently repeating an external call that
  already started.
- Native Tool, Code Mode, and `ctx.consult.run(...)` all require the same user-created intent.

## Data leaves the workspace

The complete evidence packet is sent to **every configured consultant** and persisted in the DSH
session event log. Version 0.1 does not discover or redact secrets. Before requesting a consultation,
make two separate decisions:

1. Is this material suitable for every external provider in the panel?
2. Is it suitable for local session persistence, export, and backup?

Consultants cannot fetch more files or call tools, and evidence is framed as untrusted data. Those
controls limit authority; they do not make sensitive material safe to disclose. Read
[Security and data flow](docs/security.md) before production use.

## Tested compatibility

DeepSeek Harness is a fast-moving developer preview. Rather than imply support through an open-ended
prerelease range, `dsh-consult` publishes an exact, required test matrix:

- `0.1.0-rc.7`
- `0.1.0-rc.8`
- `0.1.1-rc.1`
- `0.1.1-rc.2`

Development tracks `0.1.1-rc.2`. CI tests all four releases on Node 22.19 and retests the development
baseline on Node 24. A separate non-blocking job watches DSH `next`; a green preview job does not
expand the support claim. See [Compatibility](docs/compatibility.md) for the policy and matrix.

## Documentation

| Guide | Start here when you need to... |
| --- | --- |
| [Configuration](docs/configuration.md) | Choose routes, reasoning effort, timeouts, and size limits |
| [Usage](docs/usage.md) | Understand intents, results, Code Mode, and the service API |
| [Security](docs/security.md) | Review external transmission, persistence, and deployment controls |
| [Architecture](docs/architecture.md) | Follow fan-out, event settlement, durable delivery, and recovery |
| [Compatibility](docs/compatibility.md) | Verify a Node/DSH combination or add a new supported release |
| [Releasing](docs/releasing.md) | Publish through npm and GitHub's release workflow |

## Development

```sh
pnpm install
pnpm check
```

The test suite composes real Cordis services with fake LLM adapters and a fake Code Runtime bridge;
no model credentials are needed. `pnpm verify:compat` builds isolated temporary projects and leaves
the current checkout untouched.

Contributions are welcome—start with [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues
privately as described in [SECURITY.md](SECURITY.md).

`dsh-consult` is an early public release for an evolving DSH developer preview. Pin a tested DSH
version in production and read [CHANGELOG.md](CHANGELOG.md) before upgrading.

## License

[MIT](LICENSE)