@deepseek-ai/dsh-sdk-app 0.1.2-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/sdk-app/README.md
+README.md: 36b1964d6a22a3fa1ddc384cdf5f973b51fc1ca4
+README.zh.md: b4871e937ec1f6a7e8b03ac09a0bd03bbb0f55ca

package/README.md

@@ -0,0 +1,70 @@
+---
+description: "SDK stdio application profile for users and maintainers launching a JSON-RPC harness runtime."
+kind: "package-bundle"
+---
+
+# `@deepseek-ai/dsh-sdk-app`
+
+English | [中文](README.zh.md)
+
+## Summary
+
+The SDK stdio application as a `dsh` profile bundle over [`dsh-base`](../base/README.md). It inherits the base's disabled module-HMR policy; its patch sets the coding-agent persona, mounts an app-owned zero-option command provider, and starts [`dsh-sdk-jsonrpc-server`](../../sdk/server/README.md) only after that provider accepts the invocation. `dsh --profile sdk --help` therefore writes help and exits without claiming stdin or stdout. The standalone [`sdk-minimal`](../sdk-minimal/README.md) bundle reuses the same startup provider with its own profile name.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+The startup provider binds stdin EOF to the launcher's bounded successful shutdown. SDK protocol `shutdown`, SIGINT, and SIGTERM retain their owning server or launcher paths; disposal drains the root profile tree and persistence. Stdout is reserved for newline-delimited JSON-RPC frames. The bundle disables model-generated session titles because the SDK exposes no title surface; deterministic fallback titles remain durable without an auxiliary model request. The inherited projection cache checkpoints SDK-created sessions for later consumers; its durability barrier flushes each covered log prefix before publishing the cache row and may split otherwise coalesced JSONL runs. A deployment selects a different complete composition through profile bundles and patch files, not another app bin.
+
+| Config | Default | Behavior |
+|---|---|---|
+| `profile` | `sdk` | Profile name rendered in command help; a bundle mounting this provider sets its own shipped profile name. |
+
+`DSH_MAX_TOKENS_AS_SUCCESS` retains the SDK deployment mapping: unset or JSON `true` reports token-limited subagent completion as accepted, while JSON `false` reports it as an error. Provider/model and workspace cwd arrive through the SDK initialization request; the base profile owns adapters, tools, persistence, policy, settings, and credentials.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### SDK coding-agent persona
+
+#### What the model sees
+
+The profile supplies `You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.` before the base tool and context contributions. The exact SDK initialization route and session cwd resolve the placeholders.
+
+#### Token effect
+
+One short stable persona plus the data-dependent base prompt sections and selected tool schemas.
+
+#### KV Cache effect
+
+Stable for a fixed profile, provider, model, and tool roster. Profile changes take effect on the next process because the shipped SDK profile uses startup-only patches.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **A profile can omit the SDK server** — a custom profile selected by the TypeScript client must retain this bundle or another `dsh-sdk-jsonrpc-server` row; client initialization fails when no peer answers.
+- **User plugins can violate stdout purity** — profile and per-launch patches are trusted application composition. The shipped bundle writes no non-protocol stdout, but it cannot contain an arbitrary inserted plugin.
+- **Configuration changes require restart** — the shipped `sdk` profile uses `patchReload: startup` so one stdio connection never observes a replacement server or Agent dependency.
+
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,70 @@
+---
+description: "面向启动 JSON-RPC harness 运行时的用户与维护者，说明 SDK stdio 应用 profile。"
+kind: "package-bundle"
+---
+
+# `@deepseek-ai/dsh-sdk-app`
+
+[English](README.md) | 中文
+
+## 概述
+
+以 [`dsh-base`](../base/README.zh.md) 为基础的 SDK stdio 应用 `dsh` profile 组合包。它继承 base 默认禁用模块 HMR（热模块替换）的策略；其 patch 设置 coding agent（编程智能体）persona、挂载应用自有的零选项命令提供方，并且只在该提供方接受调用后启动 [`dsh-sdk-jsonrpc-server`](../../sdk/server/README.zh.md)。因此，`dsh --profile sdk --help` 会写出 help 并退出，不会占用 stdin 或 stdout。独立的 [`sdk-minimal`](../sdk-minimal/README.zh.md) bundle 复用同一个启动提供方，并提供自己的 profile 名称。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+启动提供方把 stdin EOF 接到启动器的有界成功关闭流程。SDK 协议 `shutdown`、SIGINT 与 SIGTERM 继续使用各自所属的 server 或启动器路径；dispose（资源释放）会排空根 profile 配置树与持久化。stdout 专用于按换行分隔的 JSON-RPC 帧。SDK 不提供 title 表层，因此本组合包禁用模型生成的 session title；确定性的 fallback title 仍会持久化，但不发起辅助模型请求。继承的投影缓存会为 SDK 创建的会话写入检查点，供后续消费方使用；其持久性屏障会在发布缓存行前 flush 所覆盖的日志前缀，因此可能拆分原本会合并的 JSONL 行。部署通过 profile 组合包与 patch 文件选择另一套完整组合，而不是使用另一个应用 bin。
+
+| 配置 | 默认值 | 行为 |
+|---|---|---|
+| `profile` | `sdk` | 命令帮助中显示的 profile 名称；挂载此提供方的 bundle 会设置自己的随附 profile 名称。 |
+
+`DSH_MAX_TOKENS_AS_SUCCESS` 保留 SDK 部署映射：未设置或 JSON `true` 把 token 达限的 subagent 完成报告为已接受，JSON `false` 则报告为错误。模型提供方／模型与工作区 cwd 通过 SDK 初始化请求传入；base profile 拥有适配器、工具、持久化、策略、settings 与 credentials。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### SDK coding agent persona
+
+#### 模型看到什么
+
+profile 会在 base 工具与上下文贡献之前提供 `You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.`。确切的 SDK 初始化路由与会话 cwd 会解析其中的占位符。
+
+#### Token 影响
+
+一段简短稳定的 persona，加上随数据变化的 base 提示词段落与所选工具 schema。
+
+#### KV Cache 影响
+
+对固定 profile、提供方、模型与工具清单保持稳定。由于随附 SDK profile 使用仅启动时 patch，profile 变化会在下一个进程生效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **profile 可以省略 SDK server**：TypeScript client 选择的自定义 profile 必须保留本组合包或另一个 `dsh-sdk-jsonrpc-server` 配置项；没有 peer 响应时，client 初始化会失败。
+- **用户插件可以破坏 stdout 纯净性**：profile 与逐次启动 patch 属于受信任应用组合。随附组合包不会向 stdout 写入非协议内容，但无法约束任意插入插件。
+- **配置变化需要重启**：随附 `sdk` profile 使用 `patchReload: startup`，因此一个 stdio 连接不会观察到 server 或 Agent 依赖被替换。
+
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# The SDK application over dsh-base. Stdout belongs exclusively to JSON-RPC.
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+- id: session-title-llm
+  disabled: true
+
+- insert:
+    - id: sdk-app-startup
+      name: '@deepseek-ai/dsh-sdk-app'
+      config:
+        profile: sdk
+
+    - id: sdk-jsonrpc-server
+      name: '@deepseek-ai/dsh-sdk-jsonrpc-server'
+      inject: [sdkAppStartup, loader]
+      config:
+        maxTokensAsSuccess: !!js "process.env.DSH_MAX_TOKENS_AS_SUCCESS === undefined ? true : JSON.parse(process.env.DSH_MAX_TOKENS_AS_SUCCESS)"

package/lib/index.js

@@ -0,0 +1,45 @@
+import { Command } from "commander";
+import z from "@deepseek-ai/schemastery";
+import { exitOnStdinEnd, parseCmdline } from "@deepseek-ai/dsh-cmdline";
+//#region lib/types/index.js
+/**
+* The SDK profile's command-line and stdin-lifetime provider. A successful
+* parse publishes {@link SDK_APP_STARTUP_SERVICE}; the JSON-RPC server waits
+* for that service, so help starts no transport.
+* @module @deepseek-ai/dsh-sdk-app
+*/
+/** Stable Cordis plugin name. */
+const name = "sdk-app-startup";
+/** Launcher service required before this app can parse its invocation. */
+const inject = ["cmdlineArgs"];
+/** Service the JSON-RPC server row waits for before claiming stdio. */
+const SDK_APP_STARTUP_SERVICE = "sdkAppStartup";
+/** Validate and default SDK stdio startup configuration. */
+const Config = z.object({ profile: z.string().default("sdk") });
+/**
+* Build this app's zero-option command and help.
+* @param profile - selected profile name rendered in the command grammar.
+* @returns a fresh program for one invocation.
+*/
+function sdkCommand(profile) {
+	return new Command().name(`dsh --profile ${profile}`).description("Serve DeepSeek Harness SDK clients over stdio JSON-RPC.").helpOption("-h, --help", "show this help").addHelpText("after", `
+Example:
+  dsh --profile ${profile}     serve one SDK runtime until its client disconnects
+`);
+}
+/**
+* Accept an SDK profile invocation, publish readiness, and bind EOF to the
+* launcher's bounded shutdown.
+* @param ctx - plugin context carrying command-line and exit launcher values.
+* @param config - selected profile identity for command help.
+*/
+function apply(ctx, config = {}) {
+	const program = sdkCommand(config.profile ?? "sdk");
+	program.action(() => {
+		exitOnStdinEnd(ctx, "sdk-app.stdin");
+		ctx.provide(SDK_APP_STARTUP_SERVICE, { accepted: true });
+	});
+	parseCmdline(ctx, program);
+}
+//#endregion
+export { Config, SDK_APP_STARTUP_SERVICE, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-sdk-app`.
+* @module @deepseek-ai/dsh-sdk-app/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-sdk-app";
+/** Cordis companion plugin name. */
+const name = "sdk-app-invariant";
+/** Service required before the companion can register. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the bundle adds a process transport and startup latch;
+* source/built stdio tests own frame purity, help exclusion, and shutdown.
+*/
+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/types/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The SDK profile's command-line and stdin-lifetime provider. A successful
+ * parse publishes {@link SDK_APP_STARTUP_SERVICE}; the JSON-RPC server waits
+ * for that service, so help starts no transport.
+ * @module @deepseek-ai/dsh-sdk-app
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name. */
+export declare const name = "sdk-app-startup";
+/** Launcher service required before this app can parse its invocation. */
+export declare const inject: string[];
+/** Service the JSON-RPC server row waits for before claiming stdio. */
+export declare const SDK_APP_STARTUP_SERVICE = "sdkAppStartup";
+/** SDK stdio startup configuration. */
+export interface Config {
+    /** Profile name rendered in help and diagnostics (default `sdk`). */
+    profile?: string;
+}
+/** Validate and default SDK stdio startup configuration. */
+export declare const Config: z<Config>;
+/**
+ * Accept an SDK profile invocation, publish readiness, and bind EOF to the
+ * launcher's bounded shutdown.
+ * @param ctx - plugin context carrying command-line and exit launcher values.
+ * @param config - selected profile identity for command help.
+ */
+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-sdk-app`.
+ * @module @deepseek-ai/dsh-sdk-app/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "sdk-app-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/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@deepseek-ai/dsh-sdk-app",
+  "description": "The dsh SDK profile bundle: stdio JSON-RPC serving and process lifecycle over dsh-base",
+  "version": "0.1.2-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/bundle/sdk-app"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.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",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "@deepseek-ai/dsh-cmdline": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-sdk-jsonrpc-server": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  }
+}