kevchess15/deepseek-harness
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
deepseek-harness/.agents/notes/implemented/architecture/2026-08-22-single-dsh-application-launcher.md

99 lines
12 KiB
Markdown
Raw Normal View History

docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
# Agent Note: One dsh launcher for application profiles
Status: implemented
English | [中文](2026-08-22-single-dsh-application-launcher.zh.md)
## Problem
DeepSeek Harness application processes need one owner for composition, plugin resolution, environment discovery, shutdown, and user customization. A dedicated app bin with a complete `cordis.yml` creates a second lifecycle beside profile launch: plugins installed into a profile do not reach it, behavior drifts from `dsh-base`, and SDK callers learn arbitrary process argv instead of the product's composition model.
docs(python): define the Windows x64 runtime contract Record win-x64 as the sole Windows Python carrier: node24-win-x64 builds a py3-none-win_amd64 wheel with dsh.exe, rg.exe, and both ConPTY addons; Windows arm64 remains explicitly unsupported. The note also pins native build ownership, shell-free pnpm launch, installed-wheel keyless/live gates, and the PowerShell-specific minimal snapshot. Update the active SEA, sole-launcher, profile-runtime, installed-wheel, and publication decisions from three runtime wheels to four, preserving their existing rationale while linking the Windows extension. Contributor and runtime references now state the exact target, filenames, sidecars, snapshot ownership, and five-wheel release set in both languages.
2026-08-23 17:11:19 +08:00
The Python SDK distributes a native executable through four platform wheels. Its packaged process uses the same profile launcher while preserving the closed VFS dependency tree, native sidecars, and installed-wheel evidence.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
## Decision
### Launch scope
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
Every supported Node application starts through the `dsh` CLI and one named profile. The shipped application commands are `dsh web`, `dsh --profile headless`, `dsh --profile sdk`, `dsh --profile sdk-minimal`, and `dsh --profile acp`; `dsh web` is the deliberate convenience alias for `--profile web`, not another application entry.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
Vendor CLIs, build-only and test-only executables, direct in-process plugin mounting, and the private browser WebWorker preview are outside the application-launch inventory. A package app bin or root demo that launches a package entry is not an accepted extension point.
### Profile applications
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
`@deepseek-ai/dsh-sdk-app` and `@deepseek-ai/dsh-acp-app` compose the full protocol applications over `@deepseek-ai/dsh-base`. The SDK bundle adds the JSON-RPC server plus app-owned help and stdio lifetime; the ACP bundle adds the automation-only ACP server plus the same application responsibilities. Both adopt the base model, tools, persistence, settings, credentials, policy, and environment behavior. The [standalone sdk-minimal profile](2026-08-24-standalone-sdk-minimal-profile.md) reuses SDK startup and JSON-RPC serving but deliberately owns a complete explicit tree without `dsh-base`.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
Profile manifests own patch reload:
| Profile | `patchReload` |
|---|---|
| `web` | `live` |
| `headless` | `startup` |
| `sdk` | `startup` |
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
| `sdk-minimal` | `startup` |
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
| `acp` | `startup` |
refactor(profiles): make module HMR opt-in Move the shared module-reload policy into dsh-base by inserting its HMR row disabled, then remove the redundant disabled overrides from Web, headless, SDK, and ACP. No shipped profile enables server module reload; live profile patch watching continues through the launcher-owned config-only fallback, and browser client HMR remains a separate mechanism. A later profile layer can opt into source-module reload explicitly with disabled: false while retaining the base root configuration. Composition tests cover every shipped mode and the explicit enable path, and the bundle references plus launcher Agent Notes document the resulting ownership and safety rationale.
2026-08-23 10:42:02 +08:00
Custom profiles default to `live`. A startup profile still applies its bundle, profile, home-level, and invocation `--patch` layers, but it does not watch them after boot. `dsh-base` inserts the module-HMR row disabled; a profile with a tested source-module reload lifecycle must enable it explicitly. None of the shipped profiles enable server module HMR: `patchReload: live` uses the launcher's config-only watcher while the startup profiles install no watcher. SDK and ACP cannot safely replace their server, agents, persistence, or tool registry inside one owned stdio connection.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
The shipped protocol profiles reserve stdout for protocol frames, expose help without starting transport, and route stdin EOF and signals through bounded root disposal. ACP remains automation-only. The SDK JSON-RPC methods, notification fields, and `initialize.serverInfo.name` remain stable. Full-profile model-visible tool and persistence defaults come from `dsh-base`; `sdk-minimal` owns its explicit defaults. Runnable snapshots own the assembled application outputs.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
### TypeScript SDK customization
`@deepseek-ai/dsh-sdk-client` depends on the same-version `@deepseek-ai/dsh` package, resolves its installed CLI module, runs it through the current Node executable, and selects `sdk` by default. Both client layers expose `dshBin`, `profile`, ordered `patches`, `dshHome`, process cwd, environment, and timeouts; arbitrary command/argv launch remains an internal fake-runtime adapter.
SDK users customize plugins through profiles. `dsh plugin --profile <name> ...` manages persistent dependencies and bundle order, the profile's `cordis.patch.yml` owns persistent row changes, and launch `patches` supply ordered ephemeral overrides. A custom profile must retain `@deepseek-ai/dsh-sdk-app` or another SDK server row. Relative CLI-module, patch, explicit home, and process-cwd paths become absolute before spawn, and initialization has a finite bound whose diagnostic names the selected profile.
Direct SDK use follows normal Harness-home resolution: explicit `dshHome`, inherited `DSH_HOME`, then `~/.dsh`. `subagent-dsh-sdk` instead requires an explicit absolute home, so a nested runtime cannot discover a person's profiles, installed plugins, credentials, or sessions through the operating-system home. DSH-specific ACP child examples also pass an isolated home; the ACP backend itself remains generic for non-DSH agents.
fix(python-sdk): harden profile runtime startup Resolve packaged profile proxies with Node ESM import conditions from each package installation, and fail loud when an explicit runtime export or legacy main entry is missing. Serialize the shared profile fallback under the existing cross-process writer lock so concurrent dsh processes cannot observe partial proxies; either carrier now replaces the other carrier’s managed entry without manual cleanup. Give Python initialize its own 10-second default bound and name the selected profile in timeout diagnostics, while leaving ordinary agent turns unbounded by default. Package the dynamically resolved web frontend and skill-badge assets so the runtime wheel’s normal dsh profiles do not depend on pkg static-discovery accidents. Rewrite the root launch rule and every active stale SDK-runtime note to the shipped dsh profile architecture in both languages. Focused tests prove import-only and transitive package exports, lock contention, cross-carrier transitions, missing-entry failures, asset inventory, and bounded initialization.
2026-08-23 19:04:19 +08:00
### Python runtime
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
refactor(repo): retire top-level examples
2026-08-24 10:00:15 +08:00
The Python runtime wheel packages the ordinary `@deepseek-ai/dsh` CLI from `node_modules/@deepseek-ai/dsh/lib/bin.js` through the private `dsh-python-runtime-closure` deploy manifest. The Python client selects `dsh --profile sdk` by default, ordered patch files, and an explicit Harness home; the runnable example under `python/sdk/examples` selects `sdk-minimal`. The installed `dsh` console command exposes the same profile grammar and the separately packaged `web` application.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
docs(python): define the Windows x64 runtime contract Record win-x64 as the sole Windows Python carrier: node24-win-x64 builds a py3-none-win_amd64 wheel with dsh.exe, rg.exe, and both ConPTY addons; Windows arm64 remains explicitly unsupported. The note also pins native build ownership, shell-free pnpm launch, installed-wheel keyless/live gates, and the PowerShell-specific minimal snapshot. Update the active SEA, sole-launcher, profile-runtime, installed-wheel, and publication decisions from three runtime wheels to four, preserving their existing rationale while linking the Windows extension. Contributor and runtime references now state the exact target, filenames, sidecars, snapshot ownership, and five-wheel release set in both languages.
2026-08-23 17:11:19 +08:00
The executable family is `deepseek-harness-sdk-runtime-<platform>-<arch>`. The SDK wire, wheel and import distribution names, sidecar names, and wire identity `deepseek-harness-sdk-runtime` remain stable. The SDK package family is `@deepseek-ai/dsh-sdk-client`, `@deepseek-ai/dsh-sdk-protocol`, and `@deepseek-ai/dsh-sdk-jsonrpc-server`; `@deepseek-ai/dsh-acp` remains the ACP protocol plugin. There is no Python-specific Node application, checked-in complete config, compatibility package, forwarding executable, fallback parser, or SDK/ACP launcher alias. The [Python profile-runtime decision](2026-08-23-python-sdk-dsh-profile-runtime.md) owns this launch, and the [Windows x64 runtime decision](2026-08-23-python-sdk-windows-x64-runtime.md) owns the fourth carrier.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
### Enforcement
fix(python-sdk): harden profile runtime startup Resolve packaged profile proxies with Node ESM import conditions from each package installation, and fail loud when an explicit runtime export or legacy main entry is missing. Serialize the shared profile fallback under the existing cross-process writer lock so concurrent dsh processes cannot observe partial proxies; either carrier now replaces the other carrier’s managed entry without manual cleanup. Give Python initialize its own 10-second default bound and name the selected profile in timeout diagnostics, while leaving ordinary agent turns unbounded by default. Package the dynamically resolved web frontend and skill-badge assets so the runtime wheel’s normal dsh profiles do not depend on pkg static-discovery accidents. Rewrite the root launch rule and every active stale SDK-runtime note to the shipped dsh profile architecture in both languages. Focused tests prove import-only and transitive package exports, lock contention, cross-carrier transitions, missing-entry failures, asset inventory, and bounded initialization.
2026-08-23 19:04:19 +08:00
`verify-application-entrypoints` scans application/package manifests, executable sources, and root demo scripts. The allowlist classifies the `dsh` product bin, vendor-excluded scope, the private WebWorker build tool, and test support. An unclassified shebang, a new package bin, or a demo wrapper that bypasses `apps/cli/src/bin.ts` fails hygiene and the primary/static CI aggregates.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
## Existing decisions and supersession
This decision supersedes the application-launch and package-name facts in [profile plugin bundles](2026-08-05-profile-plugin-bundles.md), [TypeScript SDK client and subagent backend](../feature/2026-07-27-typescript-sdk-and-sdk-subagent-backend.md), [remove the SDK project toolchain](../simplification/2026-08-11-remove-sdk-project-toolchain.md), and [single-file Python SDK runtime distribution](2026-07-10-single-file-executable-sdk-runtime-distribution.md). Those notes retain independent authority for profile layering, client/wire semantics, deleted project tooling, and native packaging.
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
The [ACP automation-only protocol](../simplification/2026-07-23-acp-automation-only-protocol.md) remains authoritative for ACP wire and interaction scope. The [repository naming contract](2026-08-11-repository-naming-contract-and-rename-ledger.md) remains authoritative for role-based package names. The [standalone sdk-minimal profile](2026-08-24-standalone-sdk-minimal-profile.md) partially supersedes this note's base-first rule and complete-tree alternative while retaining this note's launcher ownership. No active note is fully superseded or eligible for archival.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
## Alternatives considered
**Keep direct bins and state that profiles are preferred.** Rejected: documentation cannot make profiles own plugin installation, environment loading, shutdown, and tests while a supported executable bypasses them.
**Keep forwarding compatibility bins.** Rejected: a forwarding executable remains another public launch name and compatibility promise. The pre-release repository can move callers directly to profiles.
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
**Put caller-supplied complete Cordis trees behind profile wrappers.** Rejected: that centralizes argv without centralizing application composition. Full profiles use `dsh-base` plus thin app bundles so shared policy has one owner. A repository-owned, versioned standalone bundle is allowed only when an explicit roster is the product behavior, as [sdk-minimal](2026-08-24-standalone-sdk-minimal-profile.md) records.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
**Accept inline plugins or a complete `cordis.yml` in the TypeScript constructor.** Rejected: the SDK would become another package installer and application composer. Named profiles and patch files already provide persistent and per-launch customization through one resolution model.
**Resolve `dsh` only from `PATH`.** Rejected: ordinary Node processes do not reliably inherit a project-local `.bin` path. A same-version package dependency provides a deterministic runtime.
refactor(profiles): make module HMR opt-in Move the shared module-reload policy into dsh-base by inserting its HMR row disabled, then remove the redundant disabled overrides from Web, headless, SDK, and ACP. No shipped profile enables server module reload; live profile patch watching continues through the launcher-owned config-only fallback, and browser client HMR remains a separate mechanism. A later profile layer can opt into source-module reload explicitly with disabled: false while retaining the base root configuration. Composition tests cover every shipped mode and the explicit enable path, and the bundle references plus launcher Agent Notes document the resulting ownership and safety rationale.
2026-08-23 10:42:02 +08:00
**Enable module HMR in `dsh-base` and make unsafe profiles disable it.** Rejected: the shared base also underlies custom profiles, so an enabled default makes every new application remember to opt out of source-module replacement. A disabled base makes module HMR an explicit profile capability while leaving `patchReload: live` config watching available.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
**Hot-reload protocol profiles.** Rejected: replacing a protocol server or its dependencies can invalidate pending frames and SDK-owned agents. Process restart is the adoption boundary for SDK and ACP configuration changes.
docs(python): define the Windows x64 runtime contract Record win-x64 as the sole Windows Python carrier: node24-win-x64 builds a py3-none-win_amd64 wheel with dsh.exe, rg.exe, and both ConPTY addons; Windows arm64 remains explicitly unsupported. The note also pins native build ownership, shell-free pnpm launch, installed-wheel keyless/live gates, and the PowerShell-specific minimal snapshot. Update the active SEA, sole-launcher, profile-runtime, installed-wheel, and publication decisions from three runtime wheels to four, preserving their existing rationale while linking the Windows extension. Contributor and runtime references now state the exact target, filenames, sidecars, snapshot ownership, and five-wheel release set in both languages.
2026-08-23 17:11:19 +08:00
**Move the Python executable through profiles without a separate packaging proof.** Rejected: the native VFS closure, four platform wheels, profile assets, ripgrep and spawn-helper sidecars, and clean-install behavior require their own migration evidence.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
## Verification
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
- Source and built CLI acceptance cover `sdk`, `sdk-minimal`, and `acp` help, transport startup, stdout purity, EOF, signals, and root disposal.
refactor(profiles): make module HMR opt-in Move the shared module-reload policy into dsh-base by inserting its HMR row disabled, then remove the redundant disabled overrides from Web, headless, SDK, and ACP. No shipped profile enables server module reload; live profile patch watching continues through the launcher-owned config-only fallback, and browser client HMR remains a separate mechanism. A later profile layer can opt into source-module reload explicitly with disabled: false while retaining the base root configuration. Composition tests cover every shipped mode and the explicit enable path, and the bundle references plus launcher Agent Notes document the resulting ownership and safety rationale.
2026-08-23 10:42:02 +08:00
- Bundle configuration tests pin module HMR disabled in `dsh-base` and absent from shipped mode overrides; the custom live-profile e2e pins config reload through the launcher's watch-only fallback.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
- Focused unit suites cover profile launch resolution, initialization bounds, SDK retries, server readiness, and nested isolated homes with 100% coverage on the changed runtime sources.
- Keyless ACP and SDK snapshots boot real `dsh` profiles and pin protocol output plus persisted logs; the nested SDK composition boots a second real profile runtime.
- The real-API workflow caps file parallelism at four because one profile e2e file can own several complete `dsh` subprocess trees; workflow tests pin that resource bound.
fix(python-sdk): harden profile runtime startup Resolve packaged profile proxies with Node ESM import conditions from each package installation, and fail loud when an explicit runtime export or legacy main entry is missing. Serialize the shared profile fallback under the existing cross-process writer lock so concurrent dsh processes cannot observe partial proxies; either carrier now replaces the other carrier’s managed entry without manual cleanup. Give Python initialize its own 10-second default bound and name the selected profile in timeout diagnostics, while leaving ordinary agent turns unbounded by default. Package the dynamically resolved web frontend and skill-badge assets so the runtime wheel’s normal dsh profiles do not depend on pkg static-discovery accidents. Rewrite the root launch rule and every active stale SDK-runtime note to the shipped dsh profile architecture in both languages. Focused tests prove import-only and transitive package exports, lock contention, cross-carrier transitions, missing-entry failures, asset inventory, and bounded initialization.
2026-08-23 19:04:19 +08:00
- The Python suite exercises exe and node carriers; packaged-runtime scenarios, native macOS executable construction, both wheels, and clean-wheel default/MCP smokes pin the `deepseek-harness-sdk-runtime-*` artifacts and profile launch.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
- `verify-application-entrypoints` includes invalid fixtures for package bins, executable sources, package-launching demo wrappers, and unclassified demos.
## Consequences
- A user changes an SDK application's plugin composition through a named profile and ordered patches, using the same installation and resolution model as every other dsh application.
refactor(profiles): make module HMR opt-in Move the shared module-reload policy into dsh-base by inserting its HMR row disabled, then remove the redundant disabled overrides from Web, headless, SDK, and ACP. No shipped profile enables server module reload; live profile patch watching continues through the launcher-owned config-only fallback, and browser client HMR remains a separate mechanism. A later profile layer can opt into source-module reload explicitly with disabled: false while retaining the base root configuration. Composition tests cover every shipped mode and the explicit enable path, and the bundle references plus launcher Agent Notes document the resulting ownership and safety rationale.
2026-08-23 10:42:02 +08:00
- A custom profile receives live config watching without server module HMR and opts into source-module replacement only through an explicit row override.
docs(python): define the standalone minimal profile Record sdk-minimal as the narrow repository-owned exception to base-first profile composition: callers still launch only dsh and cannot provide an arbitrary Cordis tree, while the shipped bundle may own a complete explicit roster. Cross-link the launcher, profile-bundle, Python-runtime, minimal-agent, snapshot, and telemetry decisions; the supersession audit keeps each older note active because its remaining rationale is independent. Update the CLI, architecture, Python tutorial/reference, example, runtime-wheel reference, and bundle documentation. The docs distinguish the full sdk profile from sdk-minimal, explain explicit-home/plugin/patch customization, state the minimal permission and persistence choices, and retain the separately packaged web profile and frontend assets for direct dsh use. Correct dsh-base descriptions to cover base-backed profiles, make SDK startup configuration visible in the generated config catalog, add sdk-minimal to the module graph, and regenerate the base-composition graph. English and Chinese pairs are re-recorded at the exact reviewed contents.
2026-08-24 15:39:43 +08:00
- The full SDK and ACP profiles share the complete base application and one set of policy and tools; `sdk-minimal` owns its explicit standalone roster, and snapshots present intentional assembled differences.
docs: define dsh as the sole Node application launcher Record the final architecture before any runtime or file-layout changes. The decision makes named dsh profiles the only supported Node application launch path, gives TypeScript SDK callers ordered profile patches for per-launch customization, and retains the packaged Python runtime as an explicitly temporary exception with a later migration obligation. Keeping this decision in a documentation-only commit gives every following commit one stable naming, lifecycle, and compatibility reference. The English and Chinese notes and their pairing record enter together.
2026-08-23 01:43:12 +08:00
- Adding `@deepseek-ai/dsh` increases the TypeScript client's install size in exchange for a deterministic same-version runtime.
- Trusted user patches can add a plugin that writes to stdout and corrupt their own protocol stream; shipped profiles guarantee purity, not arbitrary third-party composition.
fix(python-sdk): harden profile runtime startup Resolve packaged profile proxies with Node ESM import conditions from each package installation, and fail loud when an explicit runtime export or legacy main entry is missing. Serialize the shared profile fallback under the existing cross-process writer lock so concurrent dsh processes cannot observe partial proxies; either carrier now replaces the other carrier’s managed entry without manual cleanup. Give Python initialize its own 10-second default bound and name the selected profile in timeout diagnostics, while leaving ordinary agent turns unbounded by default. Package the dynamically resolved web frontend and skill-badge assets so the runtime wheel’s normal dsh profiles do not depend on pkg static-discovery accidents. Rewrite the root launch rule and every active stale SDK-runtime note to the shipped dsh profile architecture in both languages. Focused tests prove import-only and transitive package exports, lock contention, cross-carrier transitions, missing-entry failures, asset inventory, and bounded initialization.
2026-08-23 19:04:19 +08:00
- Python packages the ordinary `dsh` profile launcher while retaining a closed native runtime and no system-Node requirement for wheel users.
Reference in a new issue Copy permalink