python: deepseek-harness SDK and runtime carrier packages

python/sdk-runtime/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
+README.md: 5543b0ba00816c230dbe4e5bba11b7bf4b38096d
+README.zh.md: 163b6d8e8373f0f770a5d95be688785907108b8a

python/sdk-runtime/README.md

@@ -0,0 +1,27 @@
+# DeepSeek Harness Runtime Wheel
+
+English | [中文](README.zh.md)
+
+Runtime carrier package for the Python SDK (dist `deepseek-harness-runtime-bin`, module `deepseek_harness_runtime`): it locates the bundled runtime binaries the `deepseek-harness` client spawns, and ships the default configuration behind zero-config runs.
+
+## Runtime carriers
+
+Two carriers coexist under `src/deepseek_harness_runtime/runtime/`, both injected by the repo's `scripts/build-exe-for-python-sdk.ts` build and both gitignored:
+
+- **exe (production)** — single-file executables `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (platform: `linux`/`macos`; arch: `x64`/`arm64`). No Node installation needed on the target machine. This is the only carrier that ships in wheel/sdist distributions.
+- **node (dev-only)** — the full deploy closure under `runtime/node/` (`package.json` + `node_modules/`), executed as `node runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js` on a system Node >= 22.19. It is the current checkout's source build, meant for repo-local development and verification only; it is never selected automatically and is excluded from distributions.
+
+Both carriers hold the same content, defined once: the [package.json](package.json) at this package's root is the deploy root of the single-exe pipeline — a pure dependency manifest (no code of its own) whose dependency closure IS both the plugin set compiled into the exe and the tree materialized into `runtime/node/`. Adding a plugin to the distribution means adding one dependency line there and rebuilding.
+
+Missing carriers raise `FileNotFoundError` naming the acquisition routes: build via `scripts/build-exe-for-python-sdk.ts` in a deepseek-harness checkout, or download the platform artifact of the `build-exe-for-python-sdk` CI workflow and place it in the runtime directory. Acquisition strategy is deliberately separate from the lookup interface, so an on-demand download can replace it later without touching callers.
+
+## Resolution API
+
+- `resolve_bundled_launch_args(mode=None) -> tuple[str, ...]` — the argv tuple that launches the bundled runtime: `(exe_path,)` in exe mode, `(node_path, bin_js_path)` in node mode. Mode selection: explicit argument > `DSH_RUNTIME_MODE` env var (`exe` | `node`) > automatic. Automatic resolution finds the production exe ONLY — the dev-only node carrier must be opted into explicitly so a production deployment can never silently ride on a source build.
+- `bundled_runtime_path() -> Path` — the platform exe path (exe carrier only; the node carrier has no single-path equivalent and launches via the argv tuple above).
+- `bundled_default_config_path() -> Path` — the checked-in default config (see below).
+- `bundled_package_dir() -> Path` — the installed package data root.
+
+## Zero-config design
+
+The runtime binary always demands an explicit config (`$DSH_CORDIS_CONFIG`, or a config path as an argv positional argument) and exits loudly without one — that hard semantic is part of the runtime's design and this package does not soften it. The bin (`dsh-jsonrpc-agent`) boots only the plugins the config lists; the serving surface (the stdio JSON-RPC server) is itself one of its entries (`@deepseek-ai/dsh-jsonrpc`), and without it the booted agent has no channel to the outside. This package checks in `runtime/cordis.yml` (the JSON-RPC serving entry, agent core, preloaded DeepSeek adapter, JSONL session persistence, local bash, each parameterized by the `DSH_*` env vars the SDK sets); when the caller uses no explicit config channel, the `deepseek_harness` client injects that file's path via `DSH_CORDIS_CONFIG` (injection conditions: [sdk README](../sdk/README.md)). Zero-config is thus an explicit, visible parameter pass in the wrapper, not a hidden fallback in the runtime.

python/sdk-runtime/README.zh.md

@@ -0,0 +1,27 @@
+# DeepSeek Harness 运行时 wheel
+
+[English](README.md) | 中文
+
+Python SDK 的运行时载体包（dist 名 `deepseek-harness-runtime-bin`，模块名 `deepseek_harness_runtime`）：它定位 `deepseek-harness` 客户端要 spawn 的内置运行时二进制，并附带支撑零配置运行的默认配置。
+
+## 运行时载体
+
+两种载体并存于 `src/deepseek_harness_runtime/runtime/` 之下，均由仓库的 `scripts/build-exe-for-python-sdk.ts` 构建注入，且均被 gitignore：
+
+- **exe（生产）**——单文件可执行程序 `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（platform：`linux`/`macos`；arch：`x64`/`arm64`）。目标机器无需安装 Node。这是唯一进入 wheel/sdist 分发物的载体。
+- **node（仅限开发）**——`runtime/node/` 下的完整 deploy 闭包（`package.json` + `node_modules/`），在系统 Node >= 22.19 上以 `node runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js` 执行。它是当前检出的源码构建，仅用于仓库本地的开发与验证；不会被自动选中，也不进入分发物。
+
+两种载体承载相同的内容，且只定义一次：本包根目录的 [package.json](package.json) 是 single-exe 流水线的 deploy root——一份零代码的纯依赖 manifest，其依赖闭包既是编译进 exe 的插件集，也是物化到 `runtime/node/` 的文件树。往分发物里加插件，就是在那里加一行依赖再重新构建。
+
+载体缺失时抛出 `FileNotFoundError` 并写明获取途径：在 deepseek-harness 检出中经 `scripts/build-exe-for-python-sdk.ts` 构建，或下载 `build-exe-for-python-sdk` CI 工作流的对应平台产物并放入 runtime 目录。获取策略与查找接口刻意分离，之后可以换成按需下载而不动任何调用方。
+
+## 解析 API
+
+- `resolve_bundled_launch_args(mode=None) -> tuple[str, ...]`——启动内置运行时的 argv 元组：exe 模式下为 `(exe_path,)`，node 模式下为 `(node_path, bin_js_path)`。模式选择：显式参数 > `DSH_RUNTIME_MODE` 环境变量（`exe` | `node`）> 自动。自动解析只找生产 exe——仅限开发的 node 载体必须显式选用，从而生产部署绝不会悄悄跑在源码构建上。
+- `bundled_runtime_path() -> Path`——平台 exe 路径（仅 exe 载体；node 载体没有单一路径的等价物，经由上面的 argv 元组启动）。
+- `bundled_default_config_path() -> Path`——检入的默认配置（见下文）。
+- `bundled_package_dir() -> Path`——已安装包的数据根目录。
+
+## 零配置设计
+
+运行时二进制始终要求显式配置（`$DSH_CORDIS_CONFIG`，或作为 argv 位置参数的配置路径），缺了就报错退出——这一硬语义是运行时设计的一部分，本包不软化它。bin（`dsh-jsonrpc-agent`）只启动配置里列出的插件；服务面（stdio JSON-RPC 服务器）也是其中一个条目（`@deepseek-ai/dsh-jsonrpc`），缺了它启动出的 agent 没有对外通道。本包检入 `runtime/cordis.yml`（JSON-RPC 服务条目、agent core、预载的 DeepSeek 适配器、JSONL 会话持久化、本地 bash，各项由 SDK 设置的 `DSH_*` 环境变量参数化）；调用方未走任何显式配置通道时，`deepseek_harness` 客户端把该文件路径注入 `DSH_CORDIS_CONFIG`（注入条件见 [sdk README](../sdk/README.md)）。零配置因此是 wrapper 里一次显式、可见的参数传递，不是运行时里的隐藏回退。

python/sdk-runtime/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deepseek-harness-runtime-bin"
+version = "0.0.0-dev"
+description = "Pinned DeepSeek Harness runtime for the Python SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+
+# Distributions carry the platform executables (build-injected, VCS-ignored —
+# hence `artifacts`) and the checked-in runtime/cordis.yml; the dev-only node
+# closure under runtime/node/ is explicitly excluded from wheel and sdist.
+[tool.hatch.build]
+artifacts = ["src/deepseek_harness_runtime/runtime/dsh-jsonrpc-agent-*"]
+exclude = ["src/deepseek_harness_runtime/runtime/node"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deepseek_harness_runtime"]

python/sdk-runtime/src/deepseek_harness_runtime/__init__.py

@@ -0,0 +1,151 @@
+"""Locate the bundled DeepSeek Harness SDK runtime shipped with this package.
+
+Two runtime carriers coexist under ``runtime/``, both injected by the repo's
+``scripts/build-exe-for-python-sdk.ts`` build (neither is checked into git):
+
+- **exe (production)**: single-file executables named
+  ``dsh-jsonrpc-agent-pkg-<platform>-<arch>`` (platform in {linux, macos}, arch in
+  {x64, arm64}); the target machine needs no Node installation.
+- **node (dev-only)**: the full deploy closure under ``runtime/node/``
+  (``package.json`` + ``node_modules/``), executed as ``node
+  runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`` on a
+  system Node >= 22.19. It is the current checkout's source build, never
+  selected automatically, and excluded from wheel/sdist distributions.
+
+``runtime/cordis.yml`` IS checked in: it is the default agent configuration
+the client SDK injects via ``$DSH_CORDIS_CONFIG`` for zero-config runs — the
+runtime itself always requires an explicit config and has no built-in
+fallback.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+PACKAGE_METADATA_FILENAME = "deepseek-harness-runtime.json"
+
+RUNTIME_MODE_ENV_VAR = "DSH_RUNTIME_MODE"
+
+_PLATFORM_TAGS = {"linux": "linux", "darwin": "macos"}
+_ARCH_TAGS = {"x86_64": "x64", "amd64": "x64", "arm64": "arm64", "aarch64": "arm64"}
+
+_EXE_ACQUISITION_HINT = (
+    "Two ways to get the executable: run `scripts/build-exe-for-python-sdk.ts` (via tsx) in a "
+    "deepseek-harness checkout, or download the platform artifact of the `build-exe-for-python-sdk` "
+    "CI workflow; place the file in this package's runtime/ directory. For local development "
+    "against a repo source build, explicitly select the dev-only node carrier with "
+    f"{RUNTIME_MODE_ENV_VAR}=node (or resolve_bundled_launch_args('node'))."
+)
+
+
+def bundled_package_dir() -> Path:
+    """Root directory of the installed runtime package data (the directory of this module)."""
+    root = Path(__file__).resolve().parent
+    metadata = root / PACKAGE_METADATA_FILENAME
+    if not metadata.is_file():
+        raise FileNotFoundError(f"deepseek-harness-runtime-bin is missing {metadata}")
+    return root
+
+
+def bundled_default_config_path() -> Path:
+    """Path of the checked-in default runtime configuration (``runtime/cordis.yml``).
+
+    The client SDK injects this path via ``$DSH_CORDIS_CONFIG`` when the caller
+    supplies no config and the launch resolves to the bundled runtime — the
+    runtime binary itself always demands an explicit config.
+    """
+    path = bundled_package_dir() / "runtime" / "cordis.yml"
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"deepseek-harness-runtime-bin is missing the default runtime config at {path}"
+        )
+    return path
+
+
+def bundled_runtime_path() -> Path:
+    """Absolute path of the bundled single-file runtime executable for the current platform.
+
+    Raises FileNotFoundError when the platform is unsupported or the executable
+    has not been placed into this package; the message names the acquisition
+    routes (acquisition strategy is deliberately separate from this lookup
+    interface, so an on-demand download can replace it without touching
+    callers).
+    """
+    tag = _current_platform_tag()
+    path = bundled_package_dir() / "runtime" / f"dsh-jsonrpc-agent-pkg-{tag}"
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"deepseek-harness-runtime-bin is missing the runtime executable at {path}. "
+            + _EXE_ACQUISITION_HINT
+        )
+    return path
+
+
+def resolve_bundled_launch_args(mode: str | None = None) -> tuple[str, ...]:
+    """The argv tuple that launches the bundled runtime.
+
+    Mode selection: the explicit ``mode`` argument wins, then the
+    ``DSH_RUNTIME_MODE`` environment variable (``exe`` | ``node``), then
+    automatic resolution. Automatic resolution finds the production exe ONLY —
+    the dev-only node carrier must be selected explicitly so a production
+    deployment can never silently ride on a source build. Returns
+    ``(exe_path,)`` in exe mode and ``(node_path, bin_js_path)`` in node mode;
+    raises FileNotFoundError when the selected carrier is unavailable and
+    ValueError for an unknown mode value.
+    """
+    selected = mode if mode is not None else os.environ.get(RUNTIME_MODE_ENV_VAR)
+    if selected is None or selected == "exe":
+        return (str(bundled_runtime_path()),)
+    if selected == "node":
+        return _node_launch_args()
+    raise ValueError(
+        f"unsupported DeepSeek Harness runtime mode {selected!r}: expected 'exe' or 'node' "
+        f"(explicit argument or ${RUNTIME_MODE_ENV_VAR})"
+    )
+
+
+def _current_platform_tag() -> str:
+    plat = _PLATFORM_TAGS.get(sys.platform)
+    arch = _ARCH_TAGS.get(platform.machine().lower())
+    if plat is None or arch is None:
+        raise FileNotFoundError(
+            "no bundled dsh-jsonrpc-agent executable exists for this platform "
+            f"(sys.platform={sys.platform!r}, machine={platform.machine()!r}); supported: "
+            "linux/macos on x64/arm64. " + _EXE_ACQUISITION_HINT
+        )
+    return f"{plat}-{arch}"
+
+
+def _node_launch_args() -> tuple[str, str]:
+    node_root = bundled_package_dir() / "runtime" / "node"
+    bin_js = (
+        node_root / "node_modules" / "@deepseek-ai" / "dsh-jsonrpc-agent" / "lib" / "bin.js"
+    )
+    if not bin_js.is_file():
+        raise FileNotFoundError(
+            f"the dev-only node runtime closure is missing at {node_root} "
+            f"(no {bin_js}); run `scripts/build-exe-for-python-sdk.ts` in a deepseek-harness "
+            "checkout, which builds and copies the deploy closure here. The node carrier "
+            "is for repo-local development only — production uses the single-file exe."
+        )
+    node = shutil.which("node")
+    if node is None:
+        raise FileNotFoundError(
+            "the node runtime mode needs a system `node` (>=22.19) on PATH; "
+            "install Node.js or use the exe mode"
+        )
+    return (node, str(bin_js))
+
+
+__all__ = [
+    "PACKAGE_METADATA_FILENAME",
+    "RUNTIME_MODE_ENV_VAR",
+    "bundled_default_config_path",
+    "bundled_package_dir",
+    "bundled_runtime_path",
+    "resolve_bundled_launch_args",
+]

python/sdk-runtime/src/deepseek_harness_runtime/deepseek-harness-runtime.json

@@ -0,0 +1 @@
+{"name":"deepseek-harness-runtime-bin","version":"0.0.0-dev"}

python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml

@@ -0,0 +1,50 @@
+# Default runtime configuration for the bundled dsh-jsonrpc-agent. The runtime
+# binary has NO built-in fallback — it always requires an explicit config via
+# `$DSH_CORDIS_CONFIG` (wins) or an argv positional path. The Python client SDK
+# injects THIS file's path via `$DSH_CORDIS_CONFIG` when the caller supplies
+# no config and the launch resolves to the bundled runtime; that explicit
+# injection is what restores the zero-config experience. The runtime bin only
+# boots this config; the serving surface (the stdio JSON-RPC server) comes
+# from the @deepseek-ai/dsh-jsonrpc entry below.
+#
+# $DSH_SESSION_ROOT and $DSH_CWD are set by the SDK per launch; the `!!js`
+# fallbacks keep this file usable when the runtime is driven manually.
+
+# The serving surface: HarnessSdkServer + line-delimited JSON-RPC transport on
+# stdio. Without this entry the runtime boots an agent nobody can talk to.
+- id: jsonrpc
+  name: '@deepseek-ai/dsh-jsonrpc'
+
+# The agent spine bundle: session store, system prompt, tool registry, agent
+# registry, and the agent loop. No pre-created agents — the SDK server creates
+# one per session/prompt sessionId.
+- id: agent-core
+  name: '@deepseek-ai/dsh-agent-core'
+
+# The DeepSeek adapter, preloaded for the stock models. The adapter fails loud
+# at load without an API key, so keyless boots must still export a dummy
+# DEEPSEEK_API_KEY (initialize/shutdown never call the model). baseURL falls
+# back to the public endpoint when unset.
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-flash
+      - deepseek-v4-pro
+
+# JSONL session persistence. $DSH_SESSION_ROOT (set by the SDK whenever
+# `session_root` is configured) wins; otherwise ./.sessions relative to the
+# runtime process cwd.
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js process.env.DSH_SESSION_ROOT ?? './.sessions'
+
+# Local bash executor behind the spine's `bash` tool. $DSH_CWD (always set by
+# the SDK) wins; otherwise the runtime process cwd.
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    cwd: !!js process.env.DSH_CWD ?? process.cwd()