dsh-camel

Chinese version: docs/README.zh-CN.md

dsh-camel keeps DeepSeek Harness tasks alive across free-model rate limits:

• Proactively pace requests when the model's request frequency is known.
• On RATE_LIMIT, show the wait/retry state in the UI and logs, then continue the same task.
• When the frequency is unknown, enable retry alone; its built-in fallback wait is 60 seconds.

Every executable capability is disabled after installation, so the package is behavior-neutral by default.

Installation

After publishing the package to npm, add the bundle to the target profile:

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

Installation only mounts the plugin; every policy remains disabled by default. Use /camel set ... inside a task to opt in without first editing the global profile.

Quick start

Enable rate-limit recovery for only the current task:

/camel set {"retry":{"enabled":true}}

If the free model allows 10 requests per minute, enable pacing as well:

/camel set {"throttle":{"enabled":true,"maxRequests":10,"windowMs":60000},"retry":{"enabled":true}}

Inspect the task override and effective policy:

/camel status

Disable all Camel behavior for this task:

/camel off

Remove the task override and inherit global plugin defaults again:

/camel reset

If global defaults are enabled, reset can enable behavior again. Use off when the task must remain disabled.

Global configuration

After installing the bundle, override its camel row in the profile's cordis.patch.yml:

- id: camel
  config:
    defaults:
      throttle:
        enabled: false
        maxRequests: 20
        windowMs: 60000
        scope: route
      retry:
        enabled: true
        mode: unlimited
        fallbackDelayMs: 60000

Task policy always has higher priority:

task session override > plugin defaults > built-in values

A launcher, preset, or another plugin can inject a one-task policy:

ctx.camel.setTaskConfig(agent, {
  retry: { enabled: true },
})

The override is persisted as a camel/config session event and survives resume and fork.

Main settings

• throttle.enabled: proactive pacing; default false.
• throttle.maxRequests: positive safe-integer request count per window.
• throttle.windowMs: window length; default 60000.
• throttle.scope: global, provider, route, or task-route.
• retry.enabled: rate-limit takeover; default false.
• retry.mode: unlimited by default; use bounded with maxRetries to stop automatically.
• retry.fallbackDelayMs: first local wait without valid Retry-After; default 60 seconds.
• retry.initialDelayMs, multiplier, and maxLocalDelayMs: later local exponential backoff.
• retry.respectRetryAfter: honor a valid provider delay first; default true.

Unknown fields, empty codes, non-positive values, non-safe-integer counts, multipliers below 1, incomplete bounded policies, and local delays above the Harness retry-event limit (2147483647ms) are rejected.

Runtime fallbacks

• Harness built-in retry gets first refusal; Camel takes over only after downstream declines.
• Task cancellation and plugin disposal cancel waits immediately. A task-policy revision interrupts the timer and re-checks takeover eligibility. A wait already written to the standard event keeps its original deadline, preventing duplicate retry events; disablement, a code mismatch, or an exhausted bounded budget stops it.
• Provider delays are not truncated by the local maxLocalDelayMs, but they are technically capped at the Harness/Node single-delay limit of 2147483647ms; unusually long throttle windows still use cancellable timer chunks.
• Non-rate-limit failures remain on the normal Harness path.
• Every takeover appends standard llm/retry and llm/retry-started events and logs the wait.
• If a retry event cannot be persisted, Camel does not return an unrecorded retry; it preserves the original rate-limit failure for the normal Harness terminal path.
• Invalid policy fails closed instead of running a partially valid configuration.

unlimited is designed to survive free-model throttling and can wait and retry for a long time. User cancellation always wins; select bounded when automatic termination is required.

Scope

This package does not handle network failures, clarification questions, continuation prompts, account rotation, or safety approvals. Those continuation policies belong to the separate dsh-continue package, and both bundles can be installed together.