dsh-llm-bounded-retry

Readme

# dsh-llm-bounded-retry

A bounded, provider-neutral retry plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

The official `@deepseek-ai/dsh-llm-retry` plugin retries selected transient failures or retries every failure without a finite limit. This plugin fills the gap between those modes: it retries every structured model-request failure up to a fixed budget, five retries by default.

## Behavior

- Default: five retries after the initial request (`maxRetries: 5`).
- Retries all structured LLM failures except `ABORTED` and cancelled requests.
- Uses durable `llm/retry` and `llm/retry-started` events, so each retry is a new agent turn.
- Uses bounded exponential backoff with symmetric jitter.
- Honors a positive provider `Retry-After` delay up to `maxDelayMs`.
- Does not wrap `ctx.llm.stream()` and cannot duplicate partial output or committed tool effects.
- Direct stream consumers are outside the agent request-error boundary.

Authentication, quota, invalid-request, and context-window failures are intentionally retried by default because the plugin implements the requested all-error policy. Use `retryableCodes: default` or an explicit array when permanent errors should be excluded.

## Install

```sh
dsh plugin --profile web add github:911218sky/dsh-llm-bounded-retry
```

The package is a DSH bundle. Installation registers its `cordis.patch.yml` automatically, disables the official `llm-retry` executor, and loads the bounded executor with the default five-retry policy. Restart the DSH profile after installation.

To override the default, add a later entry to the profile's `cordis.patch.yml`:

```yaml
- id: llm-bounded-retry
  config:
    maxRetries: 5
    retryableCodes: all
    initialDelayMs: 500
    maxDelayMs: 10000
    jitterRatio: 0.1
```

## Configuration

| Key | Default | Description |
| --- | ---: | --- |
| `maxRetries` | `5` | Retries after the initial attempt. `0` disables retry. |
| `retryableCodes` | `all` | `all`, `default`, or an array of exact failure codes. |
| `initialDelayMs` | `500` | Initial local backoff. |
| `maxDelayMs` | `10000` | Maximum local backoff and accepted provider delay. |
| `jitterRatio` | `0.1` | Symmetric jitter from 0 to 100 percent. |

## Development

The source, tests, and declaration output use TypeScript. `npm test` runs the ESM build, strict type check, and Node test suite.

```sh
npm install
npm test
npm pack --dry-run
```

## License

This project and its documentation are licensed under [CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/). See [LICENSE](LICENSE) for the license notice.