dsh-acp

Readme

# dsh-acp

![cover](docs/cover.png)

> [简体中文](docs/README.zh.md) · [技术文档 / Technical notes](docs/technical.md)

An **Agent Client Protocol (ACP)** server for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) that lets [Zed](https://zed.dev) and other IDEs drive dsh agents over **JSON-RPC 2.0 stdio**.

Built on the official [`@deepseek-ai/dsh-acp`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/acp/acp) skeleton as a dsh **profile bundle** over `dsh-base`, and extended with the editor experience of [`pi-acp`](https://github.com/svkozak/pi-acp).

## Introduction

`dsh-acp` mounts an ACP server on dsh's stdin/stdout. Zed launches `dsh --profile acp` and speaks ACP JSON-RPC over stdio; the plugin translates `session/*` requests into dsh agent lifecycles. No dsh modification required.

## Features

- **Token & thinking streaming** — `agent_message_chunk` / `agent_thought_chunk`
- **Tool cards** — `tool_call` / `tool_call_update` with kind, file location and line
- **Structured diffs** — edit/write hunks plus before/after snapshots
- **Session history** — `session/list` · `session/load` · `session/delete`
- **Session selectors** — write permission (3) · model · thinking strength
- **Agent presets** — deployment-wide preset selection via `DSH_ACP_PRESET`: the built-in `standard` / `minimal` modes (other modes need global mounting in the profile, see Configuration), plus any preset you author under `$DSH_HOME/.agent-presets/`
- **Bash terminal** — command output rendered as terminal content with exit code
- **Context-usage ring** — `usage_update` (used / size) feeds the IDE's context indicator
- **Todo list** — dsh's `todo_write` snapshots rendered as the IDE's plan checklist (`plan` update), cleared when a new turn begins
- **Image understanding** — ACP `image` prompt blocks (e.g. screenshots) admitted through dsh 0.1.1's durable attachment seam (`dsh-attachment`) and fed to the model as `ImageBlock`s, with a capability advertisement that lets Zed send images
- **Slash commands** — dsh's `/` commands advertised via `available_commands_update`, executed in the command plane (images handed to commands that accept them)
- **Ask the user** — dsh's `ask_user_question` tool answered through ACP form elicitation (options, multi-select, free text), with a self-explaining fallback for clients without the elicitation capability

## Installation

Prerequisites: Node.js ≥ 20, `dsh` (developed against `dsh@0.1.1-rc.2`), `pnpm`.

```bash
dsh plugin --profile acp add github:cnctem/dsh-acp
```

From source:

```bash
git clone https://github.com/cnctem/dsh-acp.git
dsh plugin --profile acp add ./dsh-acp
```

## Configuration

- Model/provider defaults to dsh's default model; override via `DSH_ACP_PROVIDER` / `DSH_ACP_MODEL` (or edit the `acp` row in `$DSH_HOME/profiles/acp/cordis.patch.yml`).
- Agent preset via `DSH_ACP_PRESET` — an optional field whose value directly names the preset mounted for every session: the value **is** the preset id, no roster constraint on your side. Unset or empty → `standard`; a value naming no existing preset fails session creation with an error. Valid ids are the shipped `standard` / `minimal` presets, plus any preset you author under `$DSH_HOME/.agent-presets/<id>/` (the user root is a preset root by default).
- The `code` (PTC) and `cordis` (creation) presets are not in `dsh-base`. They need the `code-runtime` and `cordis-host-runner` plugins installed globally (in the profile's `cordis.patch.yml`), after which you can pick `code` / `cordis` via `DSH_ACP_PRESET` like any other preset.
- API key reuses dsh credentials (`$DSH_HOME/.credentials.yaml` or `DEEPSEEK_API_KEY`).

## Integration

Add to Zed's `settings.json`:

```json
{
  "agent_servers": {
    "dsh": {
      "type": "custom",
      "command": "dsh",
      "args": ["--profile", "acp"],
      "env": {}
    }
  }
}
```

Restart Zed and pick `dsh`. Fix a model or preset via `env` (`DSH_ACP_PRESET` directly names the preset to mount — empty → `standard`, unknown id → session error; `standard` / `minimal` work out of the box, and globally installed presets are supported too):

```json
{
  "agent_servers": {
    "dsh-minimal": {
      "type": "custom",
      "command": "dsh",
      "args": ["--profile", "acp"],
      "env": { "DSH_ACP_PRESET": "minimal" }
    }
  }
}
```

Zed also supports multiple entries for the same acp, so different presets can coexist as separate entries in the "+" menu.

## Acknowledgements

- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and its [`@deepseek-ai/dsh-acp`](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/acp/acp) example
- [`pi-acp`](https://github.com/svkozak/pi-acp) — the reference for the richer editor experience
- [Agent Client Protocol](https://agentclientprotocol.com) and [Zed](https://zed.dev)