Skip to main content

Deepseek-Harness-Desktop/vendor/deepseek-harness/packages/bundle/headless

127Stars9Forks0Issues0Watchers

DSH One-Time Task Bundle: Delegates command-line tasks to an Agent for execution, writes the final assistant output to stdout, then exits. No port opening or Web UI.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the ChisaAlter/Deepseek-Harness-Desktop monorepo — stars and activity count the whole repository.

Language
JavaScript
License
MIT
Branch
main
deepseekdeepseek-harnessdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add @deepseek-ai/dsh-headless

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin ChisaAlter/Deepseek-Harness-Desktop/vendor/deepseek-harness/packages/bundle/headless for me: review the repository at https://github.com/ChisaAlter/Deepseek-Harness-Desktop first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

This document corresponds to the vendor/deepseek-harness/packages/bundle/headless subpath in the vendor repository and serves as the content source for the Plugin Encyclopedia module on the landing page /plugins/{owner}/{repo}.

One-Line Pitch

DSH one-shot task execution bundle: Submit a task text via command line, let the built-in Agent execute it, print the final assistant reply to stdout and exit. It doesn't open ports, doesn't bring a Web UI, and doesn't depend on the host layer—it's just a thin patch layered on top of dsh-base.

Core Capabilities

  • Parse dsh --profile headless "<task>" command line, concatenating multi-word positional parameters into a single task; missing or whitespace-only tasks are rejected before startup, the runner won't be activated (src/startup.ts:31-55 / tests/startup.spec.ts)
  • Create a brand new persistent Agent via ctx.agents, submit the task as a normal user message, wait for the Agent to naturally return to idle (src/index.ts:111-126)
  • Flush the session to disk (reusing dsh-base's JSONL session persistence), aggregate events within this execution interval, extract the final non-empty assistant text and write to stdout (src/index.ts:127-129)
  • Determine exit code based on final turn/end reason: completed exits 0; other cases (aborted / error / no turn in interval) exit 1; errors also write code and message to stderr (src/index.ts:129-133 / tests/headless.spec.ts:146-179)
  • Request exit via the launcher-provided main process hook ctx.appExit, ensuring no listening ports are opened (src/index.ts:144-149 / README.md:5-7)
  • Thin overlay on top of dsh-base: override system-prompt persona, disable HMR, set tools mode, append Code Mode worker runtime, and add two plugins headless-startup and headless-runner (cordis.patch.yml:7-35)

Technical Implementation

  • Language: TypeScript (ESM source, published as lib/index.js / lib/types/index.d.ts)
  • Key Dependencies: @deepseek-ai/dsh-cmdline (command line & appExit), @deepseek-ai/dsh-code-runtime-worker-thread (Code Mode worker runtime), commander (command line parsing), @deepseek-ai/schemastery (Config validation)
  • Architecture Pattern: cordis bundle patch — cordis.patch.yml inserts several lines on top of dsh-base and rewrites system-prompt / hmr / tools config, then injects headless-startup (command line provider) and headless-runner (task executor) two plugins; runner obtains task text via inject: [headlessStartup], startup injects cmdlineArgs and appExit via provideCmdline (cordis.patch.yml:7-35 / src/startup.ts:49-56 / src/index.ts:141-149)
  • Entry Files: src/index.ts (headless-runner), src/startup.ts (headless-startup), src/invariant.ts (package invariant placeholder, registered as empty installer)

Use Cases

Users who want to run a natural language task in CI, scripts, or one-off debugging and get a text conclusion—for example, batch running regression prompts, embedding an Agent as a command-line tool into existing workflows, or verifying a prompt in a browserless server environment. This entry records the same upstream implementation that Deepseek-Harness-Desktop vendored the upstream headless bundle into dsh-desktop; it is not a Desktop UI bearer itself.

Prerequisites & Compatibility

DependencyMinimum VersionDescription
DSH (launcher)0.1.0-rc.7+Declares 0.1.0-rc.7 itself (package.json:4); must be invoked via dsh --profile headless launcher, runner strongly depends on launcher's ctx.appExit and ctx.cmdlineArgs (src/index.ts:144-147 / src/startup.ts:13-16)
Node.js^22.19.0 || >=24.0.0Constrained by vendored harness root engines.node; bundle/headless doesn't declare separately (vendor/deepseek-harness/package.json:8-10)
PlatformCross-platformmacOS / Windows / Linux all work; doesn't depend on any native modules or platform-specific binaries (no os/cpu fields in package.json)
Native ModulesNoneThis package introduces no new native modules; underlying sqlite uses :memory: and defaults to off

Installation

dsh plugin --profile web add github:ChisaAlter/Deepseek-Harness-Desktop/vendor/deepseek-harness/packages/bundle/headless

Configuration

ConfigTypeDescriptionDefault
taskString (required)One-shot task prompt text, injected into ctx.headlessStartup.task by the command line provider then passed to runner; runtime submits the entire text as user message to Agent (src/index.ts:31-38, 122-125 / cordis.patch.yml:31-35)Provided by caller, no built-in default
DSH_TOOLS_MODE env variablenative / code / bothWritten to tools line mode field via cordis.patch.yml, controls Code Mode and native tools switch; shares same variable when stacked with web (cordis.patch.yml:18-21)Not set (follows tools plugin schema default)

FAQ

Q: What's the relationship between this bundle and dsh-base?

A: headless is a thin patch layered on top of dsh-base, not a replacement. It doesn't redundantly register any host, HTTP, Web, or browser capabilities—it only overrides system-prompt persona in dsh-base, disables HMR, forwards tools mode, appends Code Mode worker runtime, and additionally injects two plugins: headless-startup (command line provider) and headless-runner (task executor) (cordis.patch.yml:7-35).

Q: Must use --profile headless to start?

A: Yes. The headless-startup's commander name is dsh --profile headless, and the runner explicitly requires the launcher to provide ctx.appExit; starting with other profiles will lack host hooks and throw immediately at mount time (src/index.ts:144-147 / src/startup.ts:31-41).

Q: How to handle quotes in the task?

A: Just use shell quoting rules—the multi-word positional parameters get concatenated into a single task by the startup parser (src/startup.ts:51-55).

Q: How to debug failures?

A: Check exit code and stderr. Exit code 1 typically corresponds to task not completed (aborted / error / no turn in interval) or startup exceptions; errors print dsh: <code>: <message> to stderr. Direct Agent creation failures, serialization failures, or being released during loader phase also go through stderr → exit 1 path (src/index.ts:85-88, 129-133 / tests/headless.spec.ts:146-217).

Q: Will uninstall affect other profiles?

A: headless is an independent bundle, only loaded when started with --profile headless; other profiles (web, tui, desktop, etc.) each depend on their own bundle patches—deleting this package won't affect their operation (README.md:5 / cordis.patch.yml).

Q: How to provide the model key?

A: Not configured in headless package. Model selection follows dsh-base's agent-default-model, key provided via $DSH_HOME/settings.yaml's llm-deepseek: section or corresponding environment variables; headless just stacks on top (cordis.patch.yml).

Getting Started Difficulty

Beginner — just run dsh --profile headless "<task>" once and it works; this package has no additional configuration surface or persistent UI state.

Known Issues & Limitations

  • Can only submit one task; runner has no interactive follow-up entry, exits after Agent naturally returns to idle, won't read stdin or followup again (README.md:19 / src/index.ts:120-129)
  • ctx.appExit must be provided by launcher; activating headless-runner outside of dsh launcher throws immediately at mount phase with the launcher must provide ctx.appExit before the tree mounts (src/index.ts:144-147 / tests/headless.spec.ts:243-245)
  • Doesn't hold runtime invariant checks itself — ./invariant registers an empty installer, covered by launcher end-to-end tests, not audited in-process (src/invariant.ts:18-22)
  • If tree gets disposed during loader settlement, runner will directly abandon this run and not request exit (src/index.ts:99-104 / tests/headless.spec.ts:220-241)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ChisaAlter/Deepseek-Harness-Desktop/vendor/deepseek-harness/packages/bundle/headless)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory