dsh-kirocrew

Readme

# dsh-kirocrew

[![CI](https://github.com/zoahdev/dsh-kirocrew/actions/workflows/ci.yml/badge.svg)](https://github.com/zoahdev/dsh-kirocrew/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/dsh-kirocrew)](https://www.npmjs.com/package/dsh-kirocrew)

Bridge **KiroCrew** into **DeepSeek Harness**: let your `dsh` agent delegate a turn
to a persistent, self-evolving development workspace over
[ACP](https://agentclientprotocol.com) (JSON-RPC 2.0 over stdio).

> **KiroCrew** is an open-source workspace that runs on your hardware, remembers
> across sessions, and keeps working unattended. This plugin exposes that
> workspace to a DeepSeek Harness agent as a single `kiro_send` tool.

## What it does

- Registers one model-facing tool: **`kiro_send`**.
- `kiro_send` spawns `kiro-cli acp`, performs the ACP handshake
  (`initialize → session/new → session/prompt`), forwards your prompt, collects
  the agent's text chunks, and returns the final text.
- Auto-approves ACP `session/request_permission` by default (`allow_once`);
  set `autoApproveTools: false` to deny instead.

This is a **thin, honest bridge**: it forwards the prompt and returns the text.
It does not reimplement KiroCrew.

## Requirements

- Node.js 18+
- `kiro-cli` installed and signed in (KiroCrew's CLI). The ACP backend lives
  behind `kiro-cli acp`.

Install KiroCrew from its official one-liner (macOS / Linux / Windows WSL):

```bash
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
```

See the [KiroCrew repo](https://github.com/kirodotdev/KiroCrew) for the desktop
app, Docker, and Windows source-install paths.

## Install

```bash
dsh plugin add dsh-kirocrew
```

or globally:

```bash
npm install -g dsh-kirocrew
```

## Usage

```text
You: kiro_send("Write a failing test and fix it")
```

Configuration (plugin config):

```jsonc
{
  "bin": "kiro-cli",          // optional: path to kiro-cli
  "cwd": "/path/to/work",     // optional: session working directory
  "mode": "coder",            // optional: KiroCrew agent mode id
  "model": "anthropic/...",   // optional: model id
  "timeoutMs": 120000,        // optional: turn timeout
  "autoApproveTools": true    // optional: auto-allow tool permissions
}
```

Per-call overrides are also accepted by `kiro_send`: `cwd`, `mode`, `model`.

## Troubleshooting

**`failed to spawn kiro-cli (is kiro-cli installed and on PATH?)`**

The bridge could not find `kiro-cli`. Install KiroCrew, make sure `kiro-cli` is
on `PATH`, and sign in (`kiro-cli` guides device-code sign-in on first run).
You can point the plugin at an explicit path with `"bin": "/absolute/kiro-cli"`.

**`kiro-cli exited before the turn completed`**

`kiro-cli acp` failed during the handshake or turn. Re-run `kiro-cli` directly
to confirm it is signed in, then check the stderr tail included in the error.

**`request cancelled or timed out`**

The turn exceeded `timeoutMs`. Raise it for long-running unattended tasks.

## Development

```bash
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test
pnpm pack
```

Tests cover the ACP protocol (handshake, text-chunk collection, thinking-chunk
skip, permission allow/deny, error paths) without requiring a live KiroCrew.
The stdio transport's failure path is also verified (missing binary).

## Honest status

This is a community plugin, not an official DeepSeek or KiroCrew project. It is
verified at the protocol and transport-failure level; a live end-to-end run
requires your own `kiro-cli` installation and sign-in.

## License

MIT

---

# dsh-kirocrew（中文）

把 **KiroCrew** 桥接进 **DeepSeek Harness**：让 `dsh` 的 agent 通过
[ACP](https://agentclientprotocol.com)（stdio 上的 JSON-RPC 2.0）把一次对话委托给一个
持久的、自我进化的开发工作区。

> **KiroCrew** 是一个跑在你自己的硬件上、跨会话记住上下文、并能无人值守继续工作的
> 开源开发工作区。本插件把它暴露成一个 `kiro_send` 工具。

## 作用

- 注册一个面向模型的工具：**`kiro_send`**。
- 它启动 `kiro-cli acp`，完成 ACP 握手（`initialize → session/new → session/prompt`），
  转发你的提示词，收集 agent 的文本分块，返回最终文本。
- 默认自动批准 ACP 的 `session/request_permission`（`allow_once`）；设
  `autoApproveTools: false` 改为拒绝。

这是一个**轻薄、诚实的桥接**：转发提示词、返回文本，并不重新实现 KiroCrew。

## 前置条件

- Node.js 18+
- 已安装并登录 `kiro-cli`（KiroCrew 的 CLI，ACP 后端就是 `kiro-cli acp`）

安装 KiroCrew（macOS / Linux / Windows WSL）：

```bash
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh
```

桌面应用、Docker、Windows 源码安装见
[KiroCrew 仓库](https://github.com/kirodotdev/KiroCrew)。

## 安装

```bash
dsh plugin add dsh-kirocrew
```

或全局安装：

```bash
npm install -g dsh-kirocrew
```

## 使用

```text
你：kiro_send("写一个会失败的测试，然后修好它")
```

配置（插件 config）：

```jsonc
{
  "bin": "kiro-cli",          // 可选：kiro-cli 路径
  "cwd": "/path/to/work",     // 可选：会话工作目录
  "mode": "coder",            // 可选：KiroCrew agent 模式 id
  "model": "anthropic/...",   // 可选：模型 id
  "timeoutMs": 120000,        // 可选：单轮超时
  "autoApproveTools": true    // 可选：自动批准工具权限
}
```

`kiro_send` 也支持按调用覆盖 `cwd`、`mode`、`model`。

## 排障

**`failed to spawn kiro-cli (is kiro-cli installed and on PATH?)`**

找不到 `kiro-cli`。请安装 KiroCrew，确认 `kiro-cli` 在 `PATH` 上并已登录。也可以用
`"bin": "/absolute/kiro-cli"` 指定绝对路径。

**`kiro-cli exited before the turn completed`**

握手或回合失败。请先直接跑一次 `kiro-cli` 确认已登录，再看错误里附带的 stderr 尾部。

**`request cancelled or timed out`**

超过了 `timeoutMs`。长时间无人值守任务可适当调大。

## 开发

```bash
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test
pnpm pack
```

测试在无需真实 KiroCrew 的情况下覆盖 ACP 协议（握手、文本分块收集、思考分块跳过、
权限批准/拒绝、错误路径），并验证 stdio 传输的失败路径（缺失二进制）。

## 诚实声明

这是社区插件，不是 DeepSeek 或 KiroCrew 官方项目。已在协议与传输失败层面验证；
完整的端到端运行需要你自己的 `kiro-cli` 安装与登录。

## 许可证

MIT