DeepSeek Harness Long-Task Guide: Goals and Context Plugins

Introduction

Published on September 14, 2026, this technical brief breaks down three optional, independent modules inside DeepSeek Harness: goal multi-turn task execution, compact automatic context compression, and background job scheduling. DeepSeek Harness, or command-line tool dsh, is an MIT-licensed open-source Agent framework released by DeepSeek in developer preview form on August 13, 2026. The framework follows a “all-plugin” architecture. Models, tools, conversation loops and scheduling logic are all implemented through Cordis plugin components.

For long-running workloads spanning tens of minutes to multiple hours, the framework separates core long-task capabilities into three independent plugin groups. The goal plugin manages persistent multi-turn objective execution and retains full conversation logs, with a default upper limit of 256 rounds. The compact plugin automatically compresses historical dialogue once context consumption hits 80% of the model’s window, and manual compression can also be triggered via commands. The background job module runs time-consuming shell commands and sub-agent tasks using run_in_background. It includes three built-in tools: job_output, job_list, and job_kill for task collection and termination. Each Agent instance allows a default maximum of 10 concurrent background jobs.

This article is compiled from official GitHub repository documentation, README files and configuration examples. It explains state machines, default parameters, command syntax, and plugin coordination workflows, alongside guidance for connecting model endpoints. All data cited is valid as of September 14, 2026.

What Is DeepSeek Harness, and Why Split Long Tasks Into Three Separate Modules

DeepSeek Harness was open-sourced on August 13, 2026 under the MIT license. Its official README defines it as an agent harness built on the “everything is plugin” paradigm and powered by the Cordis plugin system. The official website summarizes the core concept concisely: Agent = Model + Harness. The large language model delivers reasoning capability, while the Harness gives the agent the ability to interpret environments, invoke tools, and complete tasks within real-world scenarios.

As of September 14, 2026, the GitHub repository deepseek-ai/deepseek-harness recorded 222,693 stars. The npm package @deepseek/dsh released its latest stable version 0.1.5-rc.1 on September 10, 2026, with the next release tag 0.1.5-rc2. The README explicitly marks the project as a developer preview, warning that breaking changes may occur in future updates. Four operating modes are defined officially. The standard mode implements a fully functional coding agent supporting file editing, shell operations, file search, skill invocation, planning, sub-agent scheduling and goal management.

Long-running agent workflows have three distinct pain points: task persistence across repeated LLM calls, handling context overflow, and managing long-running shell commands. Instead of bundling these functions into a monolithic “long-task mode”, DeepSeek Harness separates them into three optional plugin sets: goal, compact and jobs. The official subsystem documentation clarifies these are optional capabilities rather than mandatory components of the core agent loop. Goal and jobs are independent packages that can be enabled or disabled separately in configuration layers.

Goal Plugin: Multi-turn Persistent Task Runner

The goal plugin group enables an agent to continue working toward a long-lived objective across multiple dialogue rounds, recover from interruptions, and preserve progress and conversation history. It consists of three core sub-components: dsh-goal which manages goal state, dsh-tool-goal that exposes model call functions including get_goal, create_goal, update_goal, and dsh-goal-round-driver which automatically triggers the next round once the agent becomes idle.

The official hierarchy is structured as Goal → Goal Round → Turn → Step. One goal contains multiple rounds. Each round starts a conversation turn initiated by the goal. Within a single turn, the model may execute multiple steps of model inference and tool invocation. Human messages sent in the same conversation do not consume goal rounds or quota. Goals have four persistent states: active, paused, blocked, and complete. There are also two internal markers armed and disarmed to control whether the driver can automatically launch new rounds.

Three default configuration parameters are defined within the official config-catalog (September 2026):

• defaultMaxGoalRounds: The upper limit of goal rounds, default value is 256. The limit can be overridden on goal creation. When rounds exhaust, the driver logs a round-limit code and enters the blocked state.
• blockedAfterConsecutiveRounds: Defines the minimum number of consecutive rounds where the model reports a blocking condition before marking the goal as blocked. Default value is 3. The official prompt specification notes states “difficulty, uncertainty or remaining usable work do not count as blocked”.
• Conversation resume auto-disable rule: After conversation recovery or branch creation, any active goal is automatically set to disarmed. The agent will not resume execution automatically until a human explicitly calls resume.

Human operators control goals using the /goal command family. The syntax is summarized below, extracted from the dsh-command-goal design specification:

A documented bug fix dated September 11, 2026 is critical for long task users. Previously, clicking “pause” in the Web UI only changed state to paused. The model turn in progress continued executing, and could even invoke update_goal resume within the same turn to undo the pause. After the fix, pause triggered from the host Web button immediately terminates the ongoing turn, while pause initiated by the model itself allows proper cleanup routines.

Compact Plugin: Automatic Threshold Context Compression with Manual /compact Trigger

Compaction is an optional capability that replaces lengthy dialogue history with concise summaries. The official subsystem documentation divides it into three layers: dsh-compaction defines the interface, dsh-compaction-basic serves as the default backend, and dsh-command-compact provides human-operated /compact commands. After successful compression, selected older history segments are replaced by a summary message while recent conversation history remains intact.

Default policy parameters for the dsh-compaction-basic backend (official config catalog, September 2026):

• thresholdRatio 0.8: Compression activates once context occupies 80% of the model window.
• retainRatio 0.16: Preserves approximately the latest 16% of window space with raw uncompressed context. Users can also use absolute retainTokens instead.
• maxTokens 8192: Token ceiling for summary generation. The summarization model defaults to the active chat model, and users can specify alternative models through summarizationProvider and summarizationModel.
• compactionRetries 1, maxOverflowRetries 1: Retry once if post-compression content still exceeds threshold. One recovery retry is allowed if the model returns context overflow errors; set to 0 to disable.

Before compression runs, a deterministic tool result pruning step runs via dsh-compaction-tool-result-pruner. When a single tool output exceeds 8192 Unicode code points, it preserves the first 4096 and final 1024 characters and replaces the middle section with a placeholder. This step frees space without invoking an LLM. The official document states automatic compression runs at the agent/pre-step phase before every step. Boundary checks match tool output pairs, but do not guarantee retention of all previous messages. Extremely large tool outputs generated in earlier turns can still be truncated.

The workflow and failure modes of compaction are documented in the README. Compaction does not alter model inference logic. After compression completes, it returns statistics on saved tokens. If no compression is needed, it returns No compactable history yet.. Compression cannot start when the agent is currently executing a turn or mid-process. User prompts sent during compression will queue and process after compression finishes. Every compression event writes three event envelopes to conversation logs: compaction/start, compaction/summary, compaction/end. If the process fails, only an unrecognized start record remains and no completed summary is produced.

Background Job: Long-running Shell Commands and Sub-agents Share the Same Task Runtime

Background job is DeepSeek Harness’s universal runtime for executing long-running tasks. The official subsystem document names it Background Task Runtime. Bash commands, PTY sessions and sub-agents all register through the same ctx.jobs registration center. Each task receives an id such as bash-1 or subagent-2, and the same toolset can read output or terminate processes.

To launch a background bash task, add run_in_background: true inside bash tool calls. According to dsh-tool-bash documentation, invocation returns the job id immediately without waiting for execution to finish, and the process continues in the background. Sub-agent tool dsh-tool-subagent also supports run_in_background and enables it by default. Three controlling tools are implemented in dsh-tool-jobs.

Two rules heavily impact real-world long-task execution:

1. Concurrency limit: The registration center dsh-jobs-local uses maxConcurrentJobsPerOwner with default value 10. It counts all jobs marked running plus stopping. Even after job_kill, jobs lingering with uncleaned resources still consume slots. When the limit is hit, new startup calls fail and prompt the model to call job_kill or wait. This constraint was added in an August 11 changelog: maxParallelToolCalls only restricts parallel calls inside a single step and cannot limit background jobs across steps.
2. Wakeup completion notification: When a background job completes, the agent receives an in-conversation notification background job <id> finished. An idle agent wakes and creates a new turn. A busy agent receives notification on its next step. Wakeup has quota protection: maxConsecutiveWakes defaults to 3. After three consecutive wake triggers, notifications degrade to passive injection. Any user message resets the quota, preventing infinite self-triggering loops where a woken turn launches another background task and reawakens itself repeatedly.

How The Three Components Work Together: End-to-End Long Task Flow

The three plugin groups work in tandem during long tasks, following this workflow described in official documentation:

1. The user inputs /goal plus objective description via Web UI or TUI, or issues natural language long instructions. The model invokes create_goal to create a goal with the default 256 round cap.
2. When the agent is idle, the driver schedules a goal_round prompt. The prompt contains JSON wrapped goal text and metadata for current round / total round limit.
3. When the model invokes time-consuming commands including test suites, builds or crawlers inside one round, it uses run_in_background to start a background job. The agent proceeds to other work, and retrieves results via job_output after completion notification arrives.
4. When context consumption approaches 80% of the model window, the compaction backend prunes oversized tool outputs first, then replaces older conversation segments with summaries. Users can manually trigger /compact when the agent is idle.
5. When the goal reaches completion, the model invokes update_goal complete. A goal only enters blocked state after the blocking condition persists for three consecutive rounds. Users can pause the current turn anytime with /goal pause.
6. After conversation recovery, the goal enters disarmed state. Users need to run /goal resume or use natural language to re-enable the armed status before the model resumes automatic rounds.

These three plugins are separate entries in configuration files. Below is the minimal YAML loading snippet provided in official README:

- name: '@deepseek-ai/dsh-goal'
  config:
    defaultMaxGoalRounds: 256
- name: '@deepseek-ai/dsh-tool-goal'
  config:
    blockedAfterConsecutiveRounds: 3
- name: '@deepseek-ai/dsh-goal-round-driver'
- name: '@deepseek-ai/dsh-compaction-basic'

The official documentation also lists two critical boundary notes. The SDK one-shot invocation mode (sdk-minimal) disables the goal stack by default, as its result API only executes a single physical turn and is not designed for long-running persistent tasks. Without loading dsh-tool-jobs, background tasks cannot start, returning the error background jobs unavailable.

Model Endpoint Configuration

Model consumption for long tasks concentrates on multi-turn goal execution and compaction summary generation. Both use the same model routing path. The official Web UI guide specifies model configuration under Settings → Models. Users input DeepSeek API key to enable endpoint access immediately. The summarization model can use separate providers and custom endpoints.

Teams routing requests to multiple model endpoints can route inference traffic through Treerouter, an API gateway, to manage access control and observability across different model services.

For OpenAI-compatible endpoints supporting mainstream large model APIs, Treerouter published updated DeepSeek Harness configuration guides on August 26, 2026, including preset values, address parameters, model ID mapping and controllable model fallback rules.

Conclusion

DeepSeek Harness decomposes long agent workloads into three optional plugin groups: goal, compaction and jobs. Each group has explicit state machines and configurable default parameters: the goal module has a default round cap of 256, compaction triggers at an 80% context threshold, and background jobs allow up to 10 concurrent tasks per agent instance. The three modules share the same persistent conversation log. Goal state tracking, compression windows and task lifecycles are all recorded inside logs, which is the core strength of this framework: every action retains audit traces.

The project remains in developer preview. The parameters and field names referenced here correspond to docs/config-catalog.md in the GitHub repository. Breaking changes may arrive in subsequent releases. All data quoted in this article is valid up to September 14, 2026.

Learn more：https://treerouter.com