@deepseek-ai/dsh-headless 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/bundle/headless/README.md
+README.md: 31a4894dbb191d2244371ca7272339e96e253053
+README.zh.md: 6e8d28f10071fbab175c4f14f1aaa9618b8f598a

package/README.md

@@ -0,0 +1,20 @@
+# `@deepseek-ai/dsh-headless`
+
+English | [中文](README.zh.md)
+
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, resolved from the injected `headlessStartup` provider). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `dsh --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.
+
+## Model Experience
+
+None, as the runner submits the task as an ordinary user message; prompts and tools belong to the base and headless bundle rows.
+
+#### KV Cache effect
+
+None; the runner adds nothing to the request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
+- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the hook.

package/README.zh.md

@@ -0,0 +1,20 @@
+# `@deepseek-ai/dsh-headless`
+
+[English](README.md) | 中文
+
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`，从注入的 `headlessStartup` 提供方解析）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：普通 `headless-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），读取 `dsh --profile headless "task"` 的位置参数、打印应用自己的 `--help`，并提供 `headlessStartup`；runner 注入该服务，再从惰性配置中读取任务。缺失或只有空白的任务会在 runner 激活前被拒绝。
+
+## 模型体验
+
+无影响，因为 runner 把任务作为普通用户消息提交；提示词与工具归 base 和 headless 组合包中的相应行所有。
+
+#### KV Cache 影响
+
+无；runner 不向请求前缀添加任何内容。
+
+## 已知限制与延期工作
+
+- **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该钩子。

package/cordis.patch.yml

@@ -0,0 +1,34 @@
+# The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. An ordinary
+# provider plugin injects `cmdlineArgs`, parses the task positional
+# (`dsh --profile headless "<task>"`) and this app's --help, then the direct
+# driver creates an Agent through the core registry and prints its durable result.
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# One-shot runs never watch or reload their composition.
+- id: hmr
+  disabled: true
+
+- id: tools
+  config:
+    # Keep the same temporary process-wide Code Mode opt-in as the Web surface.
+    mode: !!js process.env.DSH_TOOLS_MODE
+
+- insert:
+    # Code Mode is a core execution capability, not a Web component.
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
+    - id: headless-startup
+      name: '@deepseek-ai/dsh-headless/startup'
+
+    # Reads its task from the ordinary headlessStartup provider.
+    - id: headless-runner
+      name: '@deepseek-ai/dsh-headless'
+      inject: [headlessStartup]
+      config:
+        task: !!js ctx.headlessStartup.task

package/lib/index.js

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import z from "@deepseek-ai/schemastery";
+import { installModelSelection } from "@deepseek-ai/dsh-agent";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { SessionId } from "@deepseek-ai/dsh-session";
+//#region lib/types/index.js
+/**
+* @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
+* rides over dsh-base without Host, HTTP, or browser plugins; this runner
+* creates one Agent through the core registry, drives the task to quiescence,
+* flushes its Session, prints the final assistant text, and exits.
+*
+* @module @deepseek-ai/dsh-headless
+*/
+/** Stable Cordis plugin name. */
+const name = "headless-runner";
+/** Core services required before the one-shot turn can start. */
+const inject = [
+	"agentDefaultModel",
+	"agents",
+	"sessions"
+];
+const Config = z.object({ task: z.string().required() });
+/** Aggregate the last assistant text and turn outcome in one owned interval. */
+function summarize(events, firstSeq) {
+	let started = false;
+	let text = "";
+	let reason;
+	for (const event of events) {
+		if (event.seq < firstSeq) continue;
+		if (event.type === "turn/start") {
+			started = true;
+			continue;
+		}
+		if (!started) continue;
+		if (event.type === "assistant/message") {
+			const joined = event.data.message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+			if (joined !== "") text = joined;
+		}
+		if (event.type === "turn/end") reason = event.data.reason;
+	}
+	return {
+		text,
+		reason
+	};
+}
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io, error) {
+	io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`);
+	io.exit(1);
+}
+/**
+* Run one task through a freshly created Agent and request process exit.
+* @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+* @param task - one-shot task text.
+* @param io - process-facing effects.
+*/
+async function run(ctx, task, io) {
+	await ctx.get("loader")?.await();
+	const agents = ctx.get("agents");
+	const defaultModel = ctx.get("agentDefaultModel");
+	const sessions = ctx.get("sessions");
+	if (agents === void 0 || defaultModel === void 0 || sessions === void 0) return;
+	const selection = defaultModel.currentSelection();
+	const { agent } = await agents.create({
+		sessionId: SessionId(`session-${randomUUID()}`),
+		meta: { cwd: process.cwd() },
+		agentOptions: {
+			provider: selection.provider,
+			model: selection.model
+		},
+		setup: (agentCtx) => {
+			installModelSelection(agentCtx, {
+				current: selection,
+				assembled: void 0
+			});
+		}
+	});
+	await agent.whenIdle();
+	const firstSeq = agent.session.seq;
+	agent.followup(createUserMessage({
+		content: [{
+			type: "text",
+			text: task
+		}],
+		source: { kind: "user" }
+	}));
+	await agent.whenIdle();
+	await sessions.flush(agent.session);
+	const outcome = summarize(agent.session.events, firstSeq);
+	io.stdout.write(outcome.text + "\n");
+	if (outcome.reason?.kind === "error") io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`);
+	io.exit(outcome.reason?.kind === "completed" ? 0 : 1);
+}
+/**
+* Mount the one-shot direct driver.
+* @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+* @param config - validated task config.
+*/
+function apply(ctx, config) {
+	const io = ctx.headlessIo;
+	if (io === void 0) throw new Error("headless-runner: the launcher must provide ctx.headlessIo before the tree mounts");
+	run(ctx, config.task, io).catch((error) => {
+		fail(io, error);
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,25 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-headless`.
+* @module @deepseek-ai/dsh-headless/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-headless";
+/** Cordis companion plugin name. */
+const name = "headless-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the runner is a one-shot driver over the API carrier
+* whose observable contract (final text on stdout, exit code by turn-end
+* reason) is process-level and owned by the launcher e2e; it registers
+* nothing and holds no mutable relation to audit inside the tree.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,46 @@
+import { Command } from "commander";
+import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
+//#region lib/types/startup.js
+/**
+* The one-shot app's command-line provider: it parses the task positional and
+* `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+* ordinary consumer whose lazy config waits for that service.
+* @module @deepseek-ai/dsh-headless/startup
+*/
+/** Stable Cordis plugin name. */
+const name = "headless-startup";
+/** Services required before the task can be resolved. */
+const inject = ["cmdlineArgs"];
+/** Service provided by this plugin and injected by the one-shot runner. */
+const HEADLESS_STARTUP_SERVICE = "headlessStartup";
+/**
+* This app's command: the task positional, its description, and its help text.
+* @returns a fresh program, so one process can parse more than once (tests).
+*/
+function headlessCommand() {
+	return new Command().name("dsh --profile headless").description("Answer one task, print the final assistant message, and exit.").helpOption("-h, --help", "show this help").argument("[task...]", "the task text; multiple words are joined by spaces").addHelpText("after", `
+Examples:
+  dsh --profile headless "run the tests"     answer one task and exit
+`);
+}
+/**
+* Turn the parsed command line into the runner's task.
+* @param program - the parsed headless command.
+* @returns the runner's service value.
+*/
+function planHeadlessStartup(program) {
+	const task = program.args.join(" ");
+	if (task.trim() === "") program.error("error: a task is required, for example: dsh --profile headless \"run the tests\"");
+	return { task };
+}
+/**
+* Parse and provide the one-shot task as an ordinary Cordis service.
+* @param ctx - plugin context carrying the command line.
+* @returns nothing once the task is provided, or when the command requested exit.
+*/
+function apply(ctx) {
+	const values = parseCmdline(ctx, headlessCommand(), planHeadlessStartup);
+	if (values !== void 0) ctx.provide(HEADLESS_STARTUP_SERVICE, values);
+}
+//#endregion
+export { HEADLESS_STARTUP_SERVICE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
+ * rides over dsh-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, drives the task to quiescence,
+ * flushes its Session, prints the final assistant text, and exits.
+ *
+ * @module @deepseek-ai/dsh-headless
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "headless-runner";
+/** Core services required before the one-shot turn can start. */
+export declare const inject: string[];
+/** Plugin config: the task resolved from this app's injected provider service. */
+export interface Config {
+    /** The prompt text for the single run. */
+    task: string;
+}
+export declare const Config: z<Config>;
+/**
+ * Process-facing effects of one run, injectable for tests. The launcher owns
+ * bounded tree shutdown and wires `exit()` to it.
+ */
+export interface HeadlessIo {
+    stdout: {
+        write(chunk: string): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    /** Request process exit with `code` after the tree disposes. */
+    exit(code: number): void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Process-facing effects provided before the headless tree mounts. */
+        headlessIo?: HeadlessIo;
+    }
+}
+/**
+ * Mount the one-shot direct driver.
+ * @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+ * @param config - validated task config.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-headless`.
+ * @module @deepseek-ai/dsh-headless/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "headless-invariant";
+/** Service required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/startup.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The one-shot app's command-line provider: it parses the task positional and
+ * `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
+ * @module @deepseek-ai/dsh-headless/startup
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Stable Cordis plugin name. */
+export declare const name = "headless-startup";
+/** Services required before the task can be resolved. */
+export declare const inject: string[];
+/** Service provided by this plugin and injected by the one-shot runner. */
+export declare const HEADLESS_STARTUP_SERVICE = "headlessStartup";
+/** What the runner row reads from {@link HEADLESS_STARTUP_SERVICE}. */
+export interface HeadlessStartupValues {
+    /** The task text this invocation asked for. */
+    task: string;
+}
+/**
+ * Parse and provide the one-shot task as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ * @returns nothing once the task is provided, or when the command requested exit.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=startup.d.ts.map

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@deepseek-ai/dsh-headless",
+  "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/bundle/headless"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/startup.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "@deepseek-ai/dsh-cmdline": "^0.0.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1",
+    "@deepseek-ai/dsh-code-runtime-worker": "^0.0.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-default-model": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-default-model": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}