deepseek-harness/packages/sdk/python-runtime/README.md

# @deepseek-ai/dsh-sdk-python-runtime

English | [中文](README.zh.md)

Private direct-config carrier for the temporarily unchanged Python SDK runtime. Its [`jsonrpc`](../server/README.md) entry serves SDK clients over newline-delimited stdio, while an external `cordis.yml` composes the spine, backends, and serving plugin. This npm package exposes no public bin and is not published; the Python SDK's existing `dsh-jsonrpc-agent-pkg-<platform>-<arch>` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) packages `lib/packaged-bin.js` from the closed deploy tree. Bare plugins resolve from that tree, while relative plugins remain configuration-relative.

## Config discovery

The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the packaged entry prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../boot/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.

A config without `dsh-sdk-jsonrpc-server` is valid and serves nothing; the carrier does not designate a server plugin.

## Exit lifecycle

stdin EOF and `SIGTERM` dispose the root to quiescence and exit 0; `SIGINT` exits 130 after the same disposal. EOF may cut off an in-flight turn as documented in the [distribution Agent Note](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md). The `jsonrpc` plugin owns response-before-exit protocol shutdown; both paths are idempotent and safe to race.

## stdout is the protocol

stdout carries only JSON-RPC frames. The carrier and boot guards diagnose on stderr, and the config must omit stdout loggers.

## Model Experience

Indirectly, through the plugins loaded from the external `cordis.yml`, which own every model-bound prompt, schema, message, and result; this carrier adds none of its own.

#### KV Cache effect

No direct invalidation; the named consumer owns any request-prefix changes.

## Known Limitations and Deferred Work

- **Temporary direct-config exception** — this private carrier remains outside `dsh --profile sdk` only to preserve the current Python executable and wheel behavior; the later Python runtime migration deletes it and then renames the executable family.
- **The carrier cannot prove that the config serves JSON-RPC** — a valid config with no `dsh-sdk-jsonrpc-server` entry boots successfully and serves nothing.
- **No built-in or default config exists** — every launch must provide `DSH_CORDIS_CONFIG` or a positional path, and deployment owns the complete plugin tree and stdout discipline.
- **stdin EOF cuts off in-flight work** — client disappearance disposes the root immediately; callers that need orderly completion use the protocol-level `shutdown` request.
refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			`# @deepseek-ai/dsh-sdk-python-runtime`
jsonrpc: SDK serving surface as plugins (dsh-jsonrpc + dsh-jsonrpc-agent) 2026-07-11 14:08:12 +08:00
docs: translate remaining READMEs 2026-07-26 05:03:53 +08:00			`English \| [中文](README.zh.md)`

refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			Private direct-config carrier for the temporarily unchanged Python SDK runtime. Its [`jsonrpc`](../server/README.md) entry serves SDK clients over newline-delimited stdio, while an external `cordis.yml` composes the spine, backends, and serving plugin. This npm package exposes no public bin and is not published; the Python SDK's existing `dsh-jsonrpc-agent-pkg-<platform>-<arch>` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) packages `lib/packaged-bin.js` from the closed deploy tree. Bare plugins resolve from that tree, while relative plugins remain configuration-relative.
jsonrpc: SDK serving surface as plugins (dsh-jsonrpc + dsh-jsonrpc-agent) 2026-07-11 14:08:12 +08:00
			`## Config discovery`

refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the packaged entry prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../boot/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
jsonrpc: SDK serving surface as plugins (dsh-jsonrpc + dsh-jsonrpc-agent) 2026-07-11 14:08:12 +08:00
refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			A config without `dsh-sdk-jsonrpc-server` is valid and serves nothing; the carrier does not designate a server plugin.
jsonrpc: SDK serving surface as plugins (dsh-jsonrpc + dsh-jsonrpc-agent) 2026-07-11 14:08:12 +08:00
			`## Exit lifecycle`

Rename RFCs to Agent Notes 2026-07-19 22:50:49 +08:00			stdin EOF and `SIGTERM` dispose the root to quiescence and exit 0; `SIGINT` exits 130 after the same disposal. EOF may cut off an in-flight turn as documented in the [distribution Agent Note](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md). The `jsonrpc` plugin owns response-before-exit protocol shutdown; both paths are idempotent and safe to race.
jsonrpc: SDK serving surface as plugins (dsh-jsonrpc + dsh-jsonrpc-agent) 2026-07-11 14:08:12 +08:00
			`## stdout is the protocol`

refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			`stdout carries only JSON-RPC frames. The carrier and boot guards diagnose on stderr, and the config must omit stdout loggers.`
Merge remote-tracking branch 'origin/master' into codex/model-experience-readmes-20260712 # Conflicts: # package.json # packages/code-runtime/code-runtime-worker/README.md # packages/workflow/tool-workflow/README.md 2026-07-14 00:34:25 +08:00
			`## Model Experience`

refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			Indirectly, through the plugins loaded from the external `cordis.yml`, which own every model-bound prompt, schema, message, and result; this carrier adds none of its own.
Merge remote-tracking branch 'origin/master' into codex/model-experience-readmes-20260712 # Conflicts: # package.json # packages/code-runtime/code-runtime-worker/README.md # packages/workflow/tool-workflow/README.md 2026-07-14 00:34:25 +08:00
docs: structure model experience fields 2026-07-19 18:08:42 +08:00			`#### KV Cache effect`

			`No direct invalidation; the named consumer owns any request-prefix changes.`
docs: document package KV cache effects 2026-07-19 17:39:50 +08:00
Merge remote-tracking branch 'origin/master' into codex/model-experience-readmes-20260712 # Conflicts: # package.json # packages/code-runtime/code-runtime-worker/README.md # packages/workflow/tool-workflow/README.md 2026-07-14 00:34:25 +08:00			`## Known Limitations and Deferred Work`

refactor(sdk): name the private Python runtime carrier explicitly Rename the relocated npm workspace to @deepseek-ai/dsh-sdk-python-runtime and the runnable example to python-sdk-agent, then update every owning English/Chinese document, test, and packaged-runtime reference. Remove the obsolete standalone bin while retaining the carrier entrypoints used to assemble the wheel runtime. This is intentionally a naming and ownership change, not a Python SDK migration. The public deepseek_harness_sdk and deepseek_harness_runtime module, wheel, executable, environment, and wire behavior remain unchanged. Documentation records that this private carrier is the temporary sole non-dsh application exception and will move to profile launch later. 2026-08-23 01:48:26 +08:00			- Temporary direct-config exception — this private carrier remains outside `dsh --profile sdk` only to preserve the current Python executable and wheel behavior; the later Python runtime migration deletes it and then renames the executable family.
			- The carrier cannot prove that the config serves JSON-RPC — a valid config with no `dsh-sdk-jsonrpc-server` entry boots successfully and serves nothing.
Merge remote-tracking branch 'origin/master' into codex/model-experience-readmes-20260712 # Conflicts: # package.json # packages/code-runtime/code-runtime-worker/README.md # packages/workflow/tool-workflow/README.md 2026-07-14 00:34:25 +08:00			- No built-in or default config exists — every launch must provide `DSH_CORDIS_CONFIG` or a positional path, and deployment owns the complete plugin tree and stdout discipline.
			- stdin EOF cuts off in-flight work — client disappearance disposes the root immediately; callers that need orderly completion use the protocol-level `shutdown` request.