dsh-critique-loop

Readme

# dsh-critique-loop

English | [中文说明](README.zh.md)

A [DeepSeek Harness (`dsh`)](https://github.com/deepseek-ai/deepseek-harness) plugin that intercepts turn completion and triggers an automatic **self-critique and improvement round**.

Ported from the Grok Build harness experiment [`Milbaxter/grok-harness`](https://github.com/Milbaxter/grok-harness).

---

## Why

Standard agent loops stop immediately when the model finishes its tool calls or responds with final text. By intercepting the terminal stopping boundary (`agent/turn-stopping`) and steering the agent before the turn closes, this plugin forces the model to review its own actions:

> "Critique what you just did. Be specific about mistakes, gaps, and weaker choices. If the critique finds something worth changing, apply the improvement now. If nothing material needs changing, say so briefly and stop."

The next stop is permitted through without looping (or up to `maxRounds`), preventing runaway continuation while ensuring thorough verification.

## Features

- 🔄 **Automatic Self-Review**: Intercepts `agent/turn-stopping` to prompt the model for immediate self-reflection.
- 🛡️ **Loop Safe**: Tracks per-turn critique counts with `WeakMap` isolation per agent; defaults to 1 round of critique per turn.
- ⚙️ **Configurable**: Customize the critique prompt, maximum review rounds, or toggle enabled/disabled.
- ⚡ **Zero Runtime Dependencies**: Pure ES module built on Cordis lifecycle hooks and native Node.js APIs.

## Installation

Add directly to your DeepSeek Harness profile from GitHub:

```bash
dsh plugin --profile web add github:Milbaxter/dsh-critique-loop
```

Or clone and add locally:

```bash
git clone https://github.com/Milbaxter/dsh-critique-loop.git
dsh plugin --profile web add ./dsh-critique-loop
```

Restart `dsh web` (or your headless session) after adding the plugin.

## Configuration

In your `cordis.yml` or bundle configuration:

```yaml
- id: dsh-critique-loop
  name: dsh-critique-loop
  config:
    enabled: true
    maxRounds: 1
    prompt: "Critique what you just did. Be specific about mistakes, gaps, and weaker choices. If the critique finds something worth changing, apply the improvement now. If nothing material needs changing, say so briefly and stop."
```

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `enabled` | `boolean` | `true` | Master switch to enable/disable the critique loop. |
| `maxRounds` | `number` | `1` | Maximum self-critique rounds per turn before stopping. |
| `prompt` | `string` | *(standard prompt)* | Custom critique instruction steered into the agent. |

## Running Tests

```bash
npm test
```

## Architecture

This plugin hooks into DeepSeek Harness's Cordis-based event system:

1. Listens on `agent/turn-stopping` (serial terminal checkpoint).
2. If `shouldCritique(agent, turn)` returns true, steers a user message with the critique prompt via `agent.steer(...)`.
3. Agent driver processes the steered input and executes another step in the open turn.
4. Subsequent stop events in the same turn are allowed through to avoid recursion.
5. On `agent/pre-step`, when genuine user messages arrive, per-turn counters are reset.

## License

[Apache 2.0](LICENSE) © [Maximilian Rehn (Milbaxter)](https://github.com/Milbaxter)