@yadsh/dsh-tool-offload

DeepSeek Harness plugin that offloads large, low-judgement tool results to small one-shot worker agents before they enter the main model context — cutting frontier-model tokens and cost on I/O-heavy workflows without touching how your agent picks tools.

Features

• Result processing, not tool replacement. The original tool executes normally under the parent agent's permissions; the plugin only rewrites the model-facing content of successful results in tools/post-execute. The canonical value stays untouched for programmatic consumers.
• Deterministic routing. Allowlist/denylist tool patterns, byte and estimated-token thresholds, and ordered selection rules pick the worker and prompt profile — no extra LLM in the routing path.
• Cheap no-tools workers. Workers start through ctx.subagents.start on a spawn-style provider with toolFilter: { allow: [] } — zero inherited model-facing tools, zero authority expansion — and an exact cheap model via agentOptions.
• Bounded parent context. The worker receives the latest user task (byte-capped), the tool name, and the serialized arguments behind explicit <PARENT_TASK> / <TOOL_CALL> / <TOOL_RESULT> data boundaries, with a prompt that treats tool output as untrusted data.
• Fail-open everywhere. Worker failure, timeout, cancellation, refusal, empty answer, or an answer that is not actually smaller — every failure mode falls back to the original result (fallback.mode: original by default; truncate and error modes available).
• Recursion-proof. Workers carry no tools and delegated child sessions are never offloaded, so an offload worker cannot spawn another offload worker.
• Bounded fan-out. Non-blocking per-agent and global worker budgets; an exhausted budget routes results through instead of queueing.
• Observability. Structured events (offload.started / offload.completed / offload.skipped / offload.worker_failed) with byte counts, reduction ratio, and skip reasons — never raw tool content — plus in-memory counters exposed through ctx.toolOffload.stats().

Install

Install the published npm package by name:

dsh plugin --profile <profile> add @yadsh/dsh-tool-offload

Requires a DSH release in the >=0.1.7-rc.2 <0.2.0 range with a subagent provider that supports tool restrictions (the in-process spawn provider).

Configuration

All keys are optional; defaults in parentheses.

| Option | Type | Default | Description | | --- | --- | --- | --- | | enabled | boolean | true | Master switch; false passes every result through untouched. | | routing.mode | allowlist | denylist | allowlist | allowlist offloads only routing.allow tools; denylist offloads everything except routing.deny. | | routing.allow | string[] | read, grep, search, web_fetch | Tool names matched exactly or by prefix* glob. | | routing.deny | string[] | bash | Tools never offloaded; wins over allow. | | routing.thresholds.minBytes | number | 24000 | Byte threshold; a result qualifies when either threshold is exceeded. | | routing.thresholds.minEstimatedTokens | number | 6000 | Cheap characters / 4 token estimate threshold. | | routing.rules | Rule[] | [] | Ordered rules; first match picks the worker/prompt profile or forces passthrough. Each rule: id, match.tools, match.minBytes, action (offload/passthrough), worker, prompt. | | workers | Record | — | Named worker profiles merged over the default profile. | | workers.<name>.subagentProvider | string | spawn | DSH subagent provider; must support tool restrictions. | | workers.<name>.provider / .model | string | null | null | Model route for the worker; null inherits the parent agent's route. Configure a cheap model here. | | workers.<name>.maxTokens | number | null | 4000 | Worker output token cap. | | workers.<name>.timeoutMs | number | 45000 | Bounded worker timeout; on timeout the original result is restored. | | defaultWorker | string | default | Worker profile used when no rule selects one. | | context.includeLastUserMessage | boolean | true | Pass the latest user task message to the worker. | | context.maxParentContextBytes | number | 12000 | Byte cap for the extracted parent task. | | payload.maxBytes | number | 300000 | Results larger than this pass through (chunking is planned). | | validation.maxOutputBytes | number | 20000 | Worker answers above this size are rejected. | | validation.requireReduction | boolean | true | Reject answers that did not actually shrink the result. | | validation.minReductionRatio | number | 0.15 | Required relative shrink (0.15 = at least 15 % smaller). | | fallback.mode | original | truncate | error | original | What replaces the result when an offload fails. | | annotation.enabled | boolean | false | Prefix transformed content with [offloaded result]. | | concurrency.maxWorkersPerAgent | number | 3 | Per-agent worker budget (non-blocking). | | concurrency.maxWorkersGlobal | number | 8 | Global worker budget (non-blocking). | | prompts | Record | — | Custom "Your job" prompt sections; generic, code-reader, search-results, web-reader, and logs are bundled. | | telemetry.enabled | boolean | true | Structured event logging; counters stay on either way. |

Built-in routing rules map the default tool candidates to bundled prompt profiles: web_fetch → web-reader, grep/search → search-results, read → code-reader; everything else uses generic.

Example cordis.patch.yml profile override:

- override:
    - id: dsh-tool-offload
      config:
        workers:
          default:
            provider: zai
            model: glm-4.5-air
            maxTokens: 4000
        routing:
          allow:
            - read
            - grep
            - web_fetch

Compatibility

• DeepSeek Harness >=0.1.7-rc.2 <0.2.0 (tested on 0.1.7-rc.2); requires the tools/post-execute seam and the subagents/start service with a tool-restriction-capable provider — see compatibility.json.
• Node.js ^22.19.0 || >=24.0.0.
• Only top-level ordinary tool results are offloaded; Code Mode (run_code) nested dispatches pass through untouched.

Development

pnpm nx run dsh-tool-offload:lint typecheck test build
pnpm nx run dsh-tool-offload:verify   # package gate

The full design document (routing policy, safety model, phased plan) lives in docs/specs/design.md; the behavioral contract is SPEC.md.

Credits

Inspired by Spotify's portal-ai-plugins/shunt, which routes I/O-heavy work to cheaper worker models. This project is a DeepSeek Harness-native implementation and does not require Spotify Portal or AiKA. See NOTICE.md.

License

MIT