@harness-flow/dsh-groupx

Readme

<h1 align="center">dsh-groupx</h1>

<p align="center">
  <strong>Bring a local GroupX multi-agent room into DeepSeek Harness.</strong><br />
  在 DSH Web 内查看本地 Agent、共享时间线，并向一个或多个 GroupX Agent 显式发送消息。
</p>

<p align="center">
  <img alt="Status: alpha" src="https://img.shields.io/badge/status-alpha-f59e0b" />
  <img alt="DSH 0.1.0-rc.6" src="https://img.shields.io/badge/DSH-0.1.0--rc.6-2563eb" />
  <img alt="Tests: 6 passing" src="https://img.shields.io/badge/tests-6%20passing-16a34a" />
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a>
</p>

> [!IMPORTANT]
> This is an independent, unofficial DSH integration for GroupX. The protocol and DSH offline-safety slice is tested; live browser E2E with real GroupX agents remains open.

## What works

- Native DSH tab at `Settings → Plugins → GroupX`.
- Loopback-only Host bridge to GroupX, defaulting to `http://127.0.0.1:4310`.
- Agent roster, status, recent semantic events, and active Turn summaries.
- Explicit single- or multi-Agent message routing through `to[]`.
- Strict rejection of sender spoofing fields and non-loopback origins.
- Safe DSH startup when GroupX is offline or incompatible.

```mermaid
flowchart LR
    U["DSH Web user"] --> P["dsh-groupx plugin"]
    P -->|"same-origin Host API"| H["DSH Host bridge"]
    H -->|"loopback REST"| G["GroupX Broker"]
    G --> C["Codex App Server"]
    G --> K["Kimi / Grok / Hermes ACP"]
    G --> A["Claude Code stream-json"]
```

DSH remains the host and UI. GroupX continues to own native Agent sessions, SQLite, memory, routing, and CLI adapters. The plugin does not bundle GroupX source, upload room data, or rewrite Agent CLI configuration.

## Status

| Gate | Result |
|---|---|
| Build and contract tests | 6/6 passed |
| Real DSH `0.1.0-rc.6` isolated boot | Passed |
| DSH Web / client module | HTTP 200 / HTTP 200 |
| GroupX offline behavior | Expected HTTP 503; DSH remains available |
| User DSH profile touched by verification | No |
| Real GroupX `0.1.13` browser E2E | Open |
| SSE resume, cancellation, restart, compaction | Planned |

The machine-readable M1 result is stored in [`evidence/m1-local-contract-2026-08-16.json`](evidence/m1-local-contract-2026-08-16.json). See [`ROADMAP.md`](ROADMAP.md) for the remaining gates.

## Quick start

### 1. Start GroupX

GroupX `0.1.13` requires Node.js `>=24.14.1 <25` and at least one configured local Agent CLI.

```powershell
npm install --global @susyimes/groupx
groupx start --no-open
```

### 2. Build and pack the DSH plugin

```powershell
git clone https://github.com/Harzva/dsh-groupx.git
cd dsh-groupx
pnpm install --frozen-lockfile
pnpm check
pnpm run pack:dsh
```

### 3. Install into the DSH Web profile

```powershell
dsh plugin --profile web add ./artifacts/harness-flow-dsh-groupx-0.1.0-alpha.0.tgz
dsh web
```

The `dsh plugin --profile <name> add <package>` form is provided by the DSH CLI and forwards installation to the selected profile.

For a different GroupX loopback port, set `DSH_GROUPX_ORIGIN` before starting DSH:

```powershell
$env:DSH_GROUPX_ORIGIN = 'http://127.0.0.1:5000'
dsh web
```

LAN, public, HTTPS, credential-bearing, and path-bearing origins are rejected.

## Development

```powershell
pnpm check
pnpm run pack:dsh
pnpm run verify:dsh-offline
```

`verify:dsh-offline` creates an isolated temporary DSH Home, installs the packed plugin into a real DSH `0.1.0-rc.6` Web profile, checks the bridge and client module, then removes the temporary profile. It does not read or modify the user's DSH profile.

## Project boundaries

| Repository | Responsibility |
|---|---|
| [`susyimes/GroupX`](https://github.com/susyimes/GroupX) | Upstream local multi-Agent broker |
| [`Harzva/GroupX`](https://github.com/Harzva/GroupX) | Harzva's upstream-tracking fork |
| `Harzva/dsh-groupx` | Independent DSH bridge and native UI |
| [`Harzva/harness-flow-hub`](https://github.com/Harzva/harness-flow-hub) | Discovery, compatibility, and future installation flows |

The local protocol study used upstream commit `a6e485f0e3ace6f59324db5fb06f032e3e199b87`. At the time of the study, the upstream tree did not declare a license, so its reference copy is excluded from Git and npm artifacts. This repository contains an independent implementation against the documented REST contract.

Architecture and product boundaries are documented in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/PRD.md`](docs/PRD.md), and [`docs/REFERENCE.md`](docs/REFERENCE.md).

## License

[MIT](LICENSE) © 2026 Harzva