dsh-subagent-admission

简体中文

An experimental shared lifecycle admission protocol and reference policy kernel for DeepSeek Harness subagents.

This project addresses the failure shape reported in Discussion #131: nested subagents can expand until one Web host becomes unresponsive. It does not add another orchestrator. It makes the decision to create or reactivate a subagent explicit, atomic, and lifecycle-owned across every caller that uses the official runtime.

The long-term product direction is an Agent Runtime Resource Control Plane: every materialising agent workload should first acquire an explicit, observable, lifecycle-owned resource permit. v0.1 deliberately tests only the DSH subagent boundary.

Release-candidate status: the source is public at yha9806/dsh-subagent-admission, while 0.1.0-rc.1 is not published to npm. This is an independent community project, not an official DeepSeek component. It has no DeepSeek endorsement or adoption, external-user evidence, production deployment, or maintainer response.

Why a shared protocol

Existing DSH plugins already solve useful local problems. In particular, dsh-turn-budget is an immediately installable, fail-closed per-turn circuit breaker built entirely on public agent/pre-step and tools/pre-execute hooks. It limits steps, tool calls, and provider tokens. dsh-background-agents limits starts made through its own tool, serialises those starts per parent, and counts existing continuable children. AgentTeams limits members inside a team, while Delegate gates declared dependencies. Those are real precedents, not gaps to erase.

dsh-turn-budget and this project address different layers and can compose: the former bounds work within one turn on stock DSH; this experiment targets atomic process/root admission shared by all callers and held through the official child lifecycle. Neither should be presented as replacing the other.

The remaining infrastructure problem is different: a tool-local lock cannot atomically govern starts made at the same time by built-in tools, other plugins, providers, SDK callers, or direct ctx.subagents calls. A host-wide capacity rule also needs to cover one-shot and continuable work, cold resume, and the official cleanup boundary. The current primary-source comparison is recorded in the ecosystem audit.

This repository therefore separates three product layers:

• a narrow, optional protocol-v1 admission contract that asks for admission before provider work or child materialisation and reports bind/release lifecycle edges;
• an external reference policy kernel implementing atomic global/root active capacity, durable root/parent cumulative fuses, ownership recovery, and typed denials;
• an operator and conformance surface providing bounded telemetry, a read-only native GUI, exact-target tests, and release evidence.

The official-facing design question is the narrow protocol contract. The current reference patch is a non-trivial lifecycle integration vehicle: 607 patch lines across three official files, with 187 changed lines in continuation.ts. It is not a “tiny hook”, and the larger plugin is not a request to move the whole product surface into DSH core.

Honest operating modes

Mode	Runtime	Behaviour
Audit	Stock npm @deepseek-ai/dsh-subagent@0.1.0-rc.6	Observes and explains activity. It never claims to block a start or solve #131.
Strict	Exact patched source target 47f943859bef60e4160492346772ded9b24f765a / source package 0.1.0-rc.5	Registers protocol v1 and enforces all-or-nothing admission before provider work.
Unavailable	Any unverified or incomplete Strict environment	Fails closed instead of silently degrading to Audit or stock behaviour.

Package semver and method presence are not enough to select Strict. The exact source identity, protocol version, patch hash, storage/bootstrap state, and single-process ownership guard must all match. See compatibility.

For an immediately installable stock-DSH turn circuit breaker, use dsh-turn-budget. Strict lifecycle admission here currently requires the exact experimental seam and should be evaluated as a reference implementation, conformance system, and upstream design prototype—not a mature zero-patch product.

Policy semantics

v0.1 is queue-free and fail-fast. Defaults are startup configuration, not GUI controls:

Limit	Default	Meaning
Global active	6	Live subagent activations in this DSH process
Per-root active	4	Live activations owned by one durable root conversation
Per-root lifetime admitted total	24	Non-refundable new-child admissions after that root enters coverage
Per-parent admitted children	8	New direct children accepted from one parent after coverage

New one-shot and continuable children consume active and cumulative capacity. A cold resume consumes active capacity without consuming cumulative quota again. A resident follow-up reuses its activation and consumes nothing new. An accepted permit remains held until the official runtime reaches quiescent cleanup; result settlement alone is not release evidence.

perRootAdmittedTotal is a mandatory positive, monotonic lifetime fuse in v0.1. It is never refunded, disabled, reset, or aged out. A sufficiently long-lived root will therefore reach 24 accepted children and remain denied for new children. That is an intentional fail-fast safety boundary for this bounded experiment, not a sustainable default for every long-running product. Future product semantics should separate always-on active caps from an optional lifetime fuse, epoch/window budgets, and audited offline reset or migration. There is deliberately no ad-hoc GUI reset path.

There is no wait queue, priority, pre-emption, force release, or GUI mutation path in v0.1.

Build and install the candidate

Prerequisites: Node ^22.19.0 || >=24.0.0 and pnpm 11.7.0.

pnpm install --frozen-lockfile
pnpm pack:plugin
pnpm exec dsh plugin --profile web add \
  "$(pwd)/dist/dsh-subagent-admission-0.1.0-rc.1.tgz"

The bundle defaults to Audit. This command does not make stock DSH enforce capacity. Strict is intentionally limited to the exact source target and reference patch documented in the upstream seam proposal:

patches/dsh-subagent-admission-seam.patch SHA-256: 1340a9ffabde8310f68a7d66c4dacecda5dba263dd51666740801f5ec2c69135.

# Prove the fixture is red against the unpatched target.
pnpm exec tsx scripts/verify-seam-patch.mts --expect-unpatched-failure

# Apply and verify protocol v1 in a disposable exact-target worktree.
pnpm exec tsx scripts/verify-seam-patch.mts

Neither command calls a model. Installing a tarball, receiving HTTP 200, or rendering the GUI is not model/API, production, adoption, or official-acceptance evidence.

Architecture

flowchart LR
  C["Built-in tools, plugins, providers, SDK callers"] --> R["Official SubagentRuntime"]
  R --> V["Normal DSH validation"]
  V --> P["Protocol-v1 prepare"]
  P -->|deny| D["Typed fail-fast denial"]
  P -->|permit| M["Provider work and materialisation"]
  M --> B["Bind child identity"]
  B --> Q["Official execution and child-owned cleanup"]
  Q --> X["Quiescent release"]
  P <--> K["Reference policy kernel"]
  K --> L["Durable cumulative ledger"]
  K --> A["Process-local active leases"]
  K --> O["Read-only snapshots and native GUI"]

The protocol never receives prompts, model output, tool arguments, provider objects, Agent instances, credentials, or disposal authority. Detailed invariants and ownership boundaries are in architecture.

Native read-only GUI

The image is captured automatically at 1440×900 from an isolated, packed DSH Web profile. It proves that the package boots in the native conversation UI, preserves the Chat and Trajectory tabs, renders four quota cards and bounded history, and exposes no mutation controls. It is automated local integration and visual evidence only—not human review, model execution, production deployment, or DeepSeek endorsement.

Reproducible evidence

All generated machine evidence lives under ignored evidence/; the repository tracks the producer, validator, and one promoted screenshot rather than pretending one machine's JSON is universal proof.

pnpm baseline:check
pnpm lint
pnpm typecheck
pnpm test
pnpm test:e2e -- tests/packed-install.e2e.ts
pnpm release:evidence
pnpm release:evidence:check

The release evidence collector produces and validates:

• exact-target Strict plus stock Audit conformance;
• JSON and SQLite crash/restart persistence fixtures;
• packed Audit/Strict installation and native GUI capture;
• raw admission timing samples with environment identity;
• a bounded, no-model structural reproduction of #131;
• a hash-bound manifest covering source fingerprint, patch, package, client bundle, reports, and promoted screenshot.

See reproduction for the safety boundary. GitHub Actions runs Linux Node 22.19/24 and macOS/Windows Node 24 checks in the public source repository. The badge and linked workflow runs are remote evidence; workflow configuration and local results alone are not. npm publication, production use, DeepSeek adoption, and maintainer response remain separate gates.

Boundaries

• Correctness is for one cooperative DSH host process. There is no multi-process, multi-host, or distributed lock.
• This is admission control, not OS process isolation, memory sandboxing, provider rate limiting, token budgeting, scheduling, or orchestration.
• Audit observes; only an exact verified protocol-v1 target can enforce.
• Cumulative quota begins at an explicit safe bootstrap. Historical work is not reconstructed or invented, and the v0.1 lifetime fuse never resets.
• A malicious in-process plugin shares the host trust boundary and can corrupt the process; v0.1 does not sandbox peer plugins.
• The current patched Strict path is a proposal and test vehicle, not an accepted upstream change or sustainable install shape. A documented, zero-patch Strict extension point is the productization gate.

Project documents

• Architecture and invariants
• Compatibility matrix and upgrade gate
• Experimental upstream seam
• Novelty and ecosystem audit
• Safe #131 reproduction
• Security policy
• Third-party notices
• Changelog

License

MIT. See LICENSE. DeepSeek Harness and other third-party components retain their own licences and notices.