Merge master projection registration API

python/development.i18n.yaml

@@ -12,8 +12,8 @@
   en: 37884fe76e167a0e
   zh: 4b6e50768c4bb945
 /python-contributor-workflows/run-against-node-source:
-  en: 7430d9e6b3d02ddc
-  zh: 9044e6be91d0ad01
+  en: 940c941d189a8248
+  zh: 321f5183383d4a12
 /python-contributor-workflows/build-distributions:
   en: 4aa941562dba5482
   zh: 50543a92b3d0cf04

python/development.md

@@ -66,6 +66,14 @@ Repository contributors can select either development route; both execute the no
 
 `python/sdk/tests/manual_sdk_agent_smoke.py` uses the internal `_launch_args` test adapter to exercise the unbuilt TypeScript CLI under tsx. Arbitrary argv replacement is intentionally absent from the public SDK.
 
+The manual [shutdown example](sdk/tests/manual_sdk_shutdown_smoke.py) uses ordinary SDK calls: run one short real-model turn, close immediately with the default 1-second budget, then open another runtime and restore the same session. Install the SDK/runtime and set `DEEPSEEK_API_KEY` before running:
+
+```sh
+python python/sdk/tests/manual_sdk_shutdown_smoke.py
+```
+
+The example prints the close duration and history files, retains its temporary directory, and lets restoration failures raise normally. Recovery uses a separate 30-second shutdown budget. Reproduction depends on the host and first-turn timing; successful restoration does not establish a shutdown latency bound. This manual example is not collected by pytest.
+
 ## Build distributions
 
 The root `package.json` version is authoritative for both Python distributions. The staging script injects that version into both wheels and pins the SDK to the same `deepseek-harness-runtime-bin` version.

python/development.zh.md

@@ -66,6 +66,14 @@ with DeepSeekHarness(dsh_home="/absolute/path/to/test-dsh-home") as harness:
 
 `python/sdk/tests/manual_sdk_agent_smoke.py` 使用内部 `_launch_args` 测试适配器，通过 tsx 验证未构建的 TypeScript CLI。公开 SDK 刻意不提供任意 argv 替换。
 
+手动[关闭示例](sdk/tests/manual_sdk_shutdown_smoke.py)只使用普通 SDK 调用：运行一轮真实模型短对话，以默认 1 秒预算立即关闭，再启动另一个运行时恢复同一会话。安装 SDK／运行时并设置 `DEEPSEEK_API_KEY` 后运行：
+
+```sh
+python python/sdk/tests/manual_sdk_shutdown_smoke.py
+```
+
+示例打印关闭耗时和历史文件列表，保留临时目录，并让恢复失败正常抛出异常。恢复进程使用独立的 30 秒关闭预算。能否复现取决于主机和首轮耗时，恢复成功不能确定关闭耗时上限。pytest 不收集此手动示例。
+
 ## 构建分发包
 
 根目录 `package.json` 的版本是两个 Python 分发包的权威版本。暂存脚本会将该版本注入两个 wheel 包，并将 SDK 固定到同版本的 `deepseek-harness-runtime-bin`。

python/sdk/tests/manual_sdk_shutdown_smoke.py

@@ -0,0 +1,36 @@
+"""Run a short SDK session, close immediately, and try restoring its history.
+
+Requires an installed SDK/runtime and DEEPSEEK_API_KEY. Run this file directly.
+The temporary Harness home is retained for inspection.
+"""
+
+from pathlib import Path
+from tempfile import mkdtemp
+from time import monotonic
+
+from deepseek_harness import DeepSeekHarness, DeepSeekHarnessConfig
+
+root = Path(mkdtemp(prefix="dsh-shutdown-"))
+config = DeepSeekHarnessConfig(
+    profile="sdk-minimal",
+    dsh_home=str(root / "home"),
+    cwd=str(root),
+    shutdown_timeout_seconds=1.0,
+)
+print("Test directory:", root)
+
+with DeepSeekHarness(config) as harness:
+    result = harness.run("只回复 OK，不要调用工具。")
+    started = monotonic()
+
+print(f"close() took {monotonic() - started:.3f}s")
+print("Reply:", result.final_response)
+if result.finish_reason != "completed":
+    raise RuntimeError(f"Model turn failed ({result.finish_reason}); check credentials and the session log.")
+print("History files:", list((root / "home" / "sessions").rglob("*.jsonl")))
+
+# Recovery gets a separate budget so its own shutdown does not repeat the test.
+config.shutdown_timeout_seconds = 30.0
+with DeepSeekHarness(config) as harness:
+    harness.resume_session(result.session_id)
+    print("History restored successfully:", result.session_id)