In conversational development environments, long-running commands such as builds, training, or downloads often block the entire session once they are started, preventing subsequent operations. The DeepSeek Harness plugin dsh-plugin-background-tasks is designed to solve this problem. It mirrors Google Antigravity’s run_command workflow experience: short commands return results immediately, long commands automatically move to the background, and the system proactively reports back when the task is complete.

Plugin Overview

  • Name: yaopushen/dsh-plugin-background-tasks
  • Maintainer: yaopushen
  • Category: Workflow
  • License: MIT

Core Features

This plugin provides the following capabilities:

  1. Asynchronous long command execution: Commands are first synchronously waited for a configured period (default 10 seconds). If the command completes within this window, the result is returned directly; otherwise, it automatically moves to the background, freeing up session resources.
  2. Proactive completion reporting: When a background task finishes, the system automatically pushes a result summary (including the exit code and output tail). No manual polling is required.
  3. On-demand status control: Each background task has a unique ID. You can list tasks, read their output, or terminate them at any time.
  4. Safe and bounded execution: Commands run through the host’s unified execution channel (ctx.shell) and are subject to session sandbox policies and approval pipelines.
  5. Ready to use out of the box: It includes a built-in “Background Task Mode” preset. Selecting this preset gives you a unified operational experience.

Installation and Enablement

Install it through the DSH plugin manager:

dsh plugin --profile web add github:yaopushen/dsh-plugin-background-tasks

After installation, select the “Background Task Mode” preset when creating a new session to enable it.

Configuration and Usage

Basic Configuration

In cordis.patch.yml or the main configuration file, you can override the plugin configuration through the config field. The key parameter is waitMsBeforeAsync, which specifies the number of milliseconds to wait synchronously. The default is 10000 (10 seconds).

# cordis.patch.yml 覆盖配置示例
- insert:
    - id: dsh-plugin-background-tasks
      name: dsh-plugin-background-tasks
      config:
        waitMsBeforeAsync: 10000   # 统一标准：10 秒

Using the Tool

Invoke the run_command tool to execute commands. Parameters include command (the full command line), cwd (working directory), description (task description), and so on.

  • Synchronous window: The synchronous waiting window is a deployment-level configuration controlled by waitMsBeforeAsync. The model cannot adjust it on a per-invocation basis.
  • Background execution: If the window expires or the invocation is aborted, the command moves to the background. The tool returns a JobId (formatted as command-N) and includes guidance for the completion notification.
  • Sandbox and permissions: Commands are subject to the session sandbox mode (only write operations are restricted, while read operations are not restricted). If you need to broaden permissions, you must use the ctx.approval approval pipeline, providing the justification (reason) and sandbox_permissions (permissions) parameters.

Notes

  • Required combinations: This plugin must be combined with a ctx.shell executor and a jobs runtime (for example, @deepseek-ai/dsh-jobs-local + @deepseek-ai/dsh-tool-jobs). If these are not combined, calls will fail.
  • Session isolation: Background tasks are isolated by the owning session. They are not visible across sessions and are canceled when the session is destroyed.
  • Security boundaries: Commands are subject to the session sandbox mode. In confining executor mode, out-of-bounds file operations are rejected. Any request to broaden permissions must go through the approval pipeline.
  • Installer behavior: The installer skips existing preset directories. To update presets, manually sync $DSH_HOME/.agent-presets/background-shell/.

Reference Resources