Merge origin/master (single-exe pipeline #253, duplication lint #281, side-sessions RFC)

Beyond line merges: python/sdk-runtime's deploy manifest gains @deepseek-ai/dsh-mode — the single-exe closure gate (verify-runtime-closure) requires every workspace peer of dsh-acp, and the bridge's type-only peer edge on dsh-mode counts; the AGENTS.md efficiency section is condensed to fit the 1820-word ceiling after master's single-exe additions. Catalogs and graphs regenerated.
2026-08-15 21:04:50 +00:00 · 2026-07-14 10:46:09 +08:00
parent c6ba5f1d26 a0359bc4a9
commit 85a2140781
145 changed files with 11508 additions and 585 deletions
--- a/python/sdk-runtime/README.i18n.yaml
+++ b/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: 4beac57526761bb150e90b60f0030ed311c4034d
+README.zh.md: c0cc0eef6a9b569105408d2f2e6321795493036a
--- a/python/sdk-runtime/README.md
+++ b/python/sdk-runtime/README.md
@@ -0,0 +1,29 @@
+# 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 distributions; this package does not publish sdists.
+- **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 install the matching platform runtime wheel produced by the `build-exe-for-python-sdk` CI workflow. The workflow retains wheels rather than standalone executable archives. Acquisition strategy is deliberately separate from the lookup interface, so an on-demand download can replace it later without touching callers.
+
+Each wheel contains exactly one executable. The fixed tags are `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, and `py3-none-macosx_11_0_arm64`; the build hook rejects `py3-none-any`, absent or multiple executables, and unsupported platform tags. The repository root `package.json` supplies the shared version for this package and the SDK, and a `python-vX.Y.Z` release tag must match it.
+
+## 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.
--- a/python/sdk-runtime/README.zh.md
+++ b/python/sdk-runtime/README.zh.md
@@ -0,0 +1,29 @@
+# DeepSeek Harness 运行时 wheel 包
+
+[English](README.md) | 中文
+
+Python SDK 的运行时载体包（分发名 `deepseek-harness-runtime-bin`，模块名 `deepseek_harness_runtime`）：它定位 `deepseek-harness` 客户端要 spawn 的内置运行时二进制，并附带支撑零配置运行的默认配置。
+
+## 运行时载体
+
+两种载体并存于 `src/deepseek_harness_runtime/runtime/` 之下，均由仓库的 `scripts/build-exe-for-python-sdk.ts` 构建注入，且均被 git 忽略：
+
+- **exe（生产）**——单文件可执行程序 `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（platform：`linux`/`macos`；arch：`x64`/`arm64`）。目标机器无需安装 Node。这是唯一随 wheel 包分发的载体；本包不发布 sdist。
+- **`node`（仅限开发）**——`runtime/node/` 下的完整部署闭包（`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 流水线的部署根目录——一份零代码的纯依赖 manifest，其依赖闭包既是编译进 exe 的插件集，也是物化到 `runtime/node/` 的文件树。往分发物里加插件，就是在那里加一行依赖再重新构建。
+
+载体缺失时抛出 `FileNotFoundError` 并写明获取途径：在 deepseek-harness 检出中经 `scripts/build-exe-for-python-sdk.ts` 构建，或安装 `build-exe-for-python-sdk` CI 工作流生成的对应平台运行时 wheel 包。该工作流只保留 wheel 包，不保留独立 exe 归档。获取策略与查找接口刻意分离，之后可以换成按需下载而不改动任何调用方。
+
+每个 wheel 包只包含一个可执行文件。固定标签为 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 与 `py3-none-macosx_11_0_arm64`；构建钩子会拒绝 `py3-none-any`、可执行文件缺失或重复以及不支持的平台标签。仓库根目录的 `package.json` 为本包和 SDK 提供共同版本，`python-vX.Y.Z` 发布标签必须与其匹配。
+
+## 解析 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)）。因此，零配置是包装层中一次显式、可见的参数传递，而不是运行时中的隐藏回退。
--- a/python/sdk-runtime/hatch_build.py
+++ b/python/sdk-runtime/hatch_build.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import os
+import platform
+import stat
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+_PLATFORMS = {
+    "linux-x64": ("manylinux_2_28_x86_64", "dsh-jsonrpc-agent-pkg-linux-x64"),
+    "linux-arm64": ("manylinux_2_28_aarch64", "dsh-jsonrpc-agent-pkg-linux-arm64"),
+    "macos-arm64": ("macosx_11_0_arm64", "dsh-jsonrpc-agent-pkg-macos-arm64"),
+}
+
+
+def _host_platform_tag() -> str:
+    machine = platform.machine().lower()
+    arch = "arm64" if machine in {"arm64", "aarch64"} else "x64" if machine in {"x86_64", "amd64"} else machine
+    system = platform.system().lower()
+    key = f"macos-{arch}" if system == "darwin" else f"linux-{arch}" if system == "linux" else system
+    try:
+        return _PLATFORMS[key][0]
+    except KeyError as exc:
+        raise RuntimeError(f"unsupported deepseek-harness-runtime-bin build platform: {key}") from exc
+
+
+class RuntimeBuildHook(BuildHookInterface):
+    """Assign the native wheel tag and reject incomplete or mixed-platform payloads."""
+
+    def initialize(self, version: str, build_data: dict[str, object]) -> None:
+        if version == "editable":
+            return
+        if self.target_name == "sdist":
+            raise RuntimeError(
+                "deepseek-harness-runtime-bin is wheel-only; build and publish platform wheels only."
+            )
+
+        platform_tag = os.environ.get("DSH_RUNTIME_PLATFORM_TAG") or _host_platform_tag()
+        matches = [value for value in _PLATFORMS.values() if value[0] == platform_tag]
+        if len(matches) != 1:
+            supported = ", ".join(value[0] for value in _PLATFORMS.values())
+            raise RuntimeError(
+                f"unsupported DSH_RUNTIME_PLATFORM_TAG {platform_tag!r}; expected one of {supported}"
+            )
+        expected_executable = matches[0][1]
+        runtime_dir = Path(self.root) / "src" / "deepseek_harness_runtime" / "runtime"
+        executables = sorted(runtime_dir.glob("dsh-jsonrpc-agent-pkg-*") if runtime_dir.is_dir() else [])
+        if [path.name for path in executables] != [expected_executable]:
+            found = ", ".join(path.name for path in executables) or "none"
+            raise RuntimeError(
+                f"runtime wheel {platform_tag} must contain only {expected_executable}; found {found}"
+            )
+        if executables[0].stat().st_mode & stat.S_IXUSR == 0:
+            raise RuntimeError(f"runtime executable is not executable: {executables[0]}")
+
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = False
+        build_data["tag"] = f"py3-none-{platform_tag}"
--- a/python/sdk-runtime/package.json
+++ b/python/sdk-runtime/package.json
@@ -0,0 +1,75 @@
+{
+  "name": "dsh-jsonrpc-agent-pkg",
+  "description": "Deploy root of the single-exe pipeline and the single source of truth unifying 'which plugins the exe bundles' and 'what the Python runtime distributes': the dependency list below IS the exe closure. Pure manifest — no code; a deploy materializes only this package.json plus node_modules.",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-acp": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-bash": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-compact": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-fs": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-hook-protocol": "workspace:^",
+    "@deepseek-ai/dsh-hooks-claude": "workspace:^",
+    "@deepseek-ai/dsh-hooks-codex": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-jsonrpc": "workspace:^",
+    "@deepseek-ai/dsh-jsonrpc-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
+    "@deepseek-ai/dsh-mode": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
+    "@deepseek-ai/dsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-scope": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-acp": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork": "workspace:^",
+    "@deepseek-ai/dsh-subagent-inprocess": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-timeout": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-cordis": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "@deepseek-ai/dsh-web-fetch-local": "workspace:^",
+    "@deepseek-ai/dsh-web-search-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-web-search-exa": "workspace:^",
+    "@deepseek-ai/dsh-web-search-perplexity": "workspace:^",
+    "@deepseek-ai/dsh-workflow": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "cordis": "workspace:^"
+  }
+}
--- a/python/sdk-runtime/pyproject.toml
+++ b/python/sdk-runtime/pyproject.toml
@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deepseek-harness-runtime-bin"
+version = "0.0.0.dev0"
+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"]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
--- a/python/sdk-runtime/src/deepseek_harness_runtime/init.py
+++ b/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 install the matching `deepseek-harness-runtime-bin` platform "
+    "wheel retained by the `build-exe-for-python-sdk` CI workflow. 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",
+]
--- a/python/sdk-runtime/src/deepseek_harness_runtime/deepseek-harness-runtime.json
+++ b/python/sdk-runtime/src/deepseek_harness_runtime/deepseek-harness-runtime.json
@@ -0,0 +1 @@
+{"name":"deepseek-harness-runtime-bin","version":"0.0.0-dev"}
--- a/python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml
+++ b/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()
				`@@ -0,0 +1 @@`
				`{"name":"deepseek-harness-runtime-bin","version":"0.0.0-dev"}`