dsh-camel

中文文档：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	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 / 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	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	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:

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.

/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.

task session override > plugin defaults > built-in values

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

- 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

/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:

'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.