dsh-camel

Readme

# dsh-camel

中文文档：[docs/README.zh-CN.md](./docs/README.zh-CN.md)

`dsh-camel` is an opt-in DeepSeek Harness plugin for free-model rate-limit recovery. It combines provider/model-aware adaptive quota learning, proactive request pacing, `Retry-After`-aware retries, visible retry status, task-scoped configuration, and session-backed activity/quota events. When a built-in retry path declines a `RATE_LIMIT` failure, Camel can keep the task alive with a configurable wait instead of letting a frequently throttled free model terminate the task.

The 0.2.x feature set also includes fixed or adaptive pacing, bounded or unlimited retry modes, per-task overrides with `task session override > plugin defaults > built-in values` precedence, `/camel status` and `/camel explain`, pause/resume controls, exact `(provider, model)` learning isolation, resume/fork-compatible event replay, and safe fallbacks when persistence or route data is unavailable. Camel never calls an LLM to classify failures or tune its policy.

Every executable policy is disabled after installation. Installing the package, or registering its optional `/camel` command, does not pace or retry any request.

## How Camel differs from related plugins

Choose `dsh-camel` when the primary problem is free-model `RATE_LIMIT` recovery and quota-aware pacing. The projects below overlap in recovery terminology, but they solve different layers of the problem.

| Related plugin | Primary focus | What Camel adds or deliberately does not do |
| --- | --- | --- |
| [`@syncended/dsh-retry`](https://www.npmjs.com/package/@syncended/dsh-retry) | Generic and transient model-error retries, provider filters, exponential backoff, and `Retry-After` | Camel is specialized for rate limits: it can pace before the limit, learn quota per exact provider/model, and wait longer or indefinitely within configured limits. It does not replace generic model-error retry. |
| [`dsh-client-auto-continue`](https://www.npmjs.com/package/dsh-client-auto-continue) / [`dsh-auto-continue`](https://github.com/HsiangNianian/dsh-auto-continue) | Web UI interruption recovery by sending a configured “continue” follow-up, with backoff, loop, and idempotency guards | Camel works at the agent request-error/retry boundary, emits standard `llm/retry` and `llm/retry-started` events, and does not inject a user prompt or require a browser UI. |
| [`@linxin666/dsh-chat-recovery`](https://www.npmjs.com/package/@linxin666/dsh-chat-recovery) | Manual Web UI recovery by editing the previous message, forking a session, and retrying a failed turn | Camel performs automatic rate-limit waiting/retry without rewriting messages or forking the conversation. |
| [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@deepseek-ai/dsh-llm-retry) | Official exact-provider agent-loop retry with durable retry events and bounded/always policies | Camel is a complementary quota layer. It gives downstream retry handlers first refusal, then takes over only when appropriate, avoiding duplicate retry events while adding adaptive pacing and free-model-specific recovery. |

These comparisons describe scope, not endorsements; check each project for its current release behavior. Camel does not choose another model, rotate accounts, or ask a model to classify failures.

`dsh-continue` is complementary rather than a comparison target here: install both when a project needs Camel's `RATE_LIMIT` protection and Continue's non-rate network recovery or safe unattended decisions. By default, Camel owns rate limits and Continue owns `TIMEOUT`, `TRANSPORT`, and `SERVER` recovery.

## Installation

Add the bundle to the target profile:

```sh
dsh plugin --profile <profile-name> add dsh-camel
```

The npm entry is this English README. The package export surface remains `dsh-camel` and `dsh-camel/cordis.patch.yml`.

## One-command task presets

Commands are available only when the host provides the optional commands service. They are task-local; they do not edit the profile.

```text
/camel preset recover
/camel preset adaptive
/camel preset bounded
```

- `recover` enables unlimited `RATE_LIMIT` retry and disables both pacing modes.
- `adaptive` enables unlimited `RATE_LIMIT` retry and adaptive pacing, while disabling fixed pacing.
- `bounded` enables five `RATE_LIMIT` retries and disables both pacing modes.

`/camel off` persistently disables all Camel policies for this task. `/camel reset` removes that task override and resumes inheritance from plugin defaults, which can therefore re-enable an explicitly configured global policy. With an attached session, `/camel set`, every preset, `/camel off`, `/camel reset`, and `ctx.camel.setTaskConfig()` append `camel/config` before changing the in-memory override. If that append throws, the operation throws, preserves the previous override, and makes no partial persisted or in-memory change. This is intentionally different from pause control's local fallback.

## Configuration and precedence

`defaults` is optional. Built-in values include throttle, retry, and adaptive numbers, but all three `enabled` values are `false`.

```text
task session override > plugin defaults > built-in values
```

An advanced profile configuration with two exact provider/model routes looks like this:

```yaml
- id: camel
  config:
    defaults:
      retry:
        enabled: true
        mode: unlimited
        fallbackDelayMs: 60000
      throttle:
        enabled: true
        maxRequests: 20
        windowMs: 60000
        scope: route
      adaptive:
        enabled: false
        initialRequests: 10
        minRequests: 1
        maxRequests: 20
        windowMs: 60000
        safetyRatio: 0.85
        decreaseRatio: 0.7
        increaseAfterWindows: 3
        stateTtlMs: 86400000
        routes:
          - provider: provider-a
            model: model-v3
            enabled: true
            initialRequests: 8
            maxRequests: 12
          - provider: provider-b
            model: model-r1
            enabled: true
            initialRequests: 4
            maxRequests: 6
```

Replace each example route with the exact resolved `request.provider` and `request.model` strings used by the Harness adapter. Route matching is an exact pair, not a display name, prefix, wildcard, or failure-message guess. Different models on one provider never share learned capacity. A missing or empty model disables adaptive reads and writes for that request; static fixed pacing and `RATE_LIMIT` retry still follow their own enabled policies.

When adaptive pacing is enabled for a resolved route, it alone owns pacing for that route. Fixed throttle is not applied a second time. Adaptive admission uses `max(minRequests, floor(learnedRequests × safetyRatio))`; a matching `RATE_LIMIT` lowers the learned count with `decreaseRatio`, and clean completed windows can raise it one step after `increaseAfterWindows`. Learning is bounded by `minRequests` and `maxRequests`, expires after `stateTtlMs`, and never calls a model to classify failures or tune policy.

For one resolved provider/model route, Camel keeps one canonical shared learning state. A task's `minRequests`, `maxRequests`, and clean-window threshold are applied as that task's admission and display view; merely reading the state never rewrites another task's learned capacity or TTL. Within one live runtime, equal-time session snapshots merge conservatively regardless of task startup order, and the shorter TTL wins for the same state version. A later real learning transition may establish the TTL from the policy that produced that transition. New quota snapshots also carry the current `rateLimitedInWindow` marker; a legacy snapshot without it is restored conservatively as a potentially rate-limited partial window.

All counts are positive safe integers; ratios are finite values in `(0, 1]`; and `minRequests <= initialRequests <= maxRequests`. `bounded` retry requires `maxRetries`. Unknown or invalid fields fail closed rather than running a partial policy.

## Status, pause, and explanation

```text
/camel status
/camel explain
/camel pause 10m
/camel resume
```

`status` returns JSON containing the task override, effective policy, pause deadline, latest activity, and touched route snapshots. `explain` gives a concise current reason, such as adaptive pacing or a scheduled retry. `pause` defaults to ten minutes and accepts positive integer `ms`, `s`, `m`, or `h` durations. While paused, Camel delegates instead of pacing or taking over a retry; `resume` clears the pause.

## Retry and persistence boundaries

Camel only owns configured rate-limit codes (by default `RATE_LIMIT`). It gives downstream recovery first refusal. In a setup with `dsh-continue`, `dsh-continue` remains responsible for non-rate network recovery, while Camel may take over `RATE_LIMIT` only after downstream declines. Camel does not rotate accounts, select or fall back to another model, answer clarification prompts, approve actions, or make model-based judgments.

Successful takeover writes standard `llm/retry` and `llm/retry-started` events. Camel also uses these version-1, non-model-visible session event shapes:

```ts
'camel/config': { version: 1, override: CamelPolicyPatch | null, source: 'command' | 'api' }
'camel/control': { version: 1, pausedUntil: number | null }
'camel/quota': AdaptiveQuotaSnapshot & { version: 1 }
// AdaptiveQuotaSnapshot = { route, learnedRequests, cooldownUntilMs, cleanWindows, windowStartedAtMs, updatedAtMs, rateLimitedInWindow? }
'camel/activity': { version: 1, kind, provider, model?, attempt?, reasonCode?, deadlineMs?, policySource }
```

`kind` is one of `pacing`, `cooldown`, `retry-scheduled`, `retry-started`, `delegated`, `cancelled`, or `exhausted`; `policySource` is `adaptive`, `throttle`, or `retry`. A standard `llm/retry` contains `retryId`, `turn`, `step`, `provider`, `retry`, `delayMs`, `failure`, and Camel's `policyKey`, and always includes `mode`; `maxRetries` is included only in bounded mode. `llm/retry-started` contains `retryId`, `turn`, `step`, and `retry` (it has no `provider` field). New Camel retry IDs can encode a resolved model; legacy provider-only IDs remain readable for retry-history compatibility.

Existing version-1 `camel/config` and standard retry history remain readable, so resumed or forked tasks retain compatible task configuration and retry ordinals. Quota and control events appended successfully to a session can be replayed on resume. Within one live Camel runtime/plugin instance, tasks on the same exact provider/model route share adaptive state; separate runtime instances, separate processes, and sessions without resumed event replay do not share it.

If custom quota or activity persistence fails, Camel logs the issue and continues the request with in-memory state. If pause-control persistence fails, the pause remains local to the live task and a warning is logged. If a required standard retry event cannot be appended, Camel does not return an unrecorded retry decision.

## Scope

Camel deliberately excludes account/key rotation, provider reconfiguration, model switching, automatic model fallback, global quota storage, and non-rate network recovery. Use `dsh-continue` for its implemented continuation behavior; this package does not claim any unimplemented `dsh-continue` capability.