# Compatibility research

Tài liệu này ghi lại các seam đã kiểm tra trước khi chốt specification. Các kết
luận đều dựa trên source local, không dựa vào việc sửa core DSH.

Research target hiện tại của DSH là `@deepseek-ai/dsh-root@0.1.0-rc.5`, commit
`47f943859bef60e4160492346772ded9b24f765a`. Đây là baseline để dựng package và
test; manifest dsh-ecc phải pin range/commit tương thích và CI phải re-verify
API export trước mỗi release.

## 0. DSH plugin install và resource discovery

DSH hiện dùng profile-scoped package installation, không dùng
`.dsh/plugins`:

~~~text
DSH_HOME (configured > $DSH_HOME > ~/.dsh)
  profiles/<profile>/package.json
  profiles/<profile>/node_modules/<plugin-package>   # logical location
~~~

`dsh plugin --profile <profile> <pnpm args>` forward pnpm với cwd là profile
directory. `reconcilePlugins()` đưa dependency có `dsh.bundle.patch` vào
`dsh.profile.bundles`; `loadProfile()` resolve bundle từ DSH installation anchor
hoặc profile package tree. Vì pnpm có store/symlink và DSH còn có
`profiles/node_modules` fallback, package root phải lấy từ DSH/module resolver,
không hard-code physical `node_modules` path.

dsh-ecc sẽ đóng gói assets trong chính package:

~~~text
<resolved dsh-ecc package root>/assets/ecc/
  agents/*.md
  skills/*/SKILL.md
~~~

`EccSourceManager` dùng asset root này cho bundled mode của MVP. Remote update là
kế hoạch hậu MVP: revision được cache dưới
`<DSH_HOME>/cache/dsh-ecc/ecc/<revision>` và chỉ đổi active pointer sau verify.
ECC files không được lấy từ cwd, DSH `.agent-presets`, global skill root hoặc
checkout local của tác giả.

### 0.1 Distribution implication

DSH profile plugin management already forwards pnpm, so dsh-ecc can expose one
community install command without a DSH core change:

~~~text
dsh plugin --profile <profile> add https://github.com/staavanothanh/dsh-ecc/releases/download/v<version>/staavanothanh-dsh-ecc-<version>.tgz
~~~

The repository preview command is:

~~~text
dsh plugin --profile <profile> add github:staavanothanh/dsh-ecc#v<version>
~~~

The package `@staavanothanh/dsh-ecc` must declare `dsh.bundle.patch`, publish
compiled `dist` plus the full `assets/ecc` closure, and retain ECC MIT
attribution. GitHub release tarballs are the stable community channel; a tag
checkout is only a development fallback. Each release pins the scoped package
version, ECC revision/integrity and DSH dependency range. A post-MVP pipeline
will track ECC releases, rebuild the bundle, run the compatibility suite and
publish a new artifact.
The release test must install from the package into a clean temporary
`DSH_HOME`; a repository checkout path is not evidence of a valid release.

## 1. ECC asset và DSH seam

| ECC asset | ECC source/format | DSH seam phù hợp | Cách adapter xử lý |
| --- | --- | --- | --- |
| Agent definitions | ECC/agents/<name>.md, frontmatter name, description, tools, model, body persona | ctx.subagents.startContinuable, child persona, parent tool composition, descriptor cold-resume | EccPersonaCatalog resolve persona id; PersonaNormalizer strips `tools`/`model`; child inherits effective parent tool scope; không đưa vào agent-presets |
| Skills | ECC/skills/<name>/SKILL.md, frontmatter và body | ctx.skills.registerProvider; tool-skill catalog/invocation | EccSkillProvider đăng ký skills; chỉ expose namespace `/ecc:<name>` |
| Rules/commands/MCP | ECC root tương ứng | Không thuộc MVP | không load và không giả vờ tương thích |

MVP community install dùng bundled snapshot pin theo dsh-ecc release.

Kế hoạch hậu MVP thêm remote update từ ECC Git ref/commit pin vào
DSH-managed cache, atomic revision swap và giữ revision cũ nếu
update/network/verify thất bại.

Không dùng local path mặc định của tác giả và không fetch main/latest trong lúc
plugin startup.

## 2. Settings và model selection

DSH SettingsProvider (packages/settings/settings/src/index.ts) resolve
schema/default/user layer và expose get, watch, update, replace. File
settings.yaml chỉ là một persistence backend; plugin không được tự parse file.

DSH llm-pi-ai lưu profile theo route trong namespace settings. Mỗi profile có
reasoningEfforts, còn request runtime dùng singular reasoningEffort. DSH
ctx.llm.resolveModelInfo(provider, model) trả metadata chính xác; sau đó
ctx.llm.resolveCallConfig({provider, model, reasoningEffort?}) kiểm tra route và
effort. Effort không hợp lệ phải fail trước provider I/O, không được tự clamp.
Nếu model không công bố effort, plugin bỏ reasoningEffort khỏi request.

agent-default-model chỉ cung cấp default selection của session. Nó không phải
store cho từng child. dsh-ecc dùng settings/LLM runtime để validate và resolve,
nhưng snapshot {provider, model, reasoningEffort} của child phải được plugin
persist riêng để cold-resume ổn định.

## 3. Continuable child

DSH ctx.subagents.startContinuable tạo child durable và trả child id. DSH
followup resume child hiện tại hoặc cold-resume từ descriptor. DSH
registerContinuableSetup chạy cho child mới và child cold-resumed.

Child hiện chỉ có provider và model trong AgentOptions; effort phải được cài theo
child-scoped agent/request listener bằng installModelSelection. Persona thì đã
được DSH request/descriptor hỗ trợ: startContinuable snapshot persona và
coldResume đưa descriptor.persona vào composition. Đây là lý do adapter chỉ cần
resolve persona id từ ECC, không cần tự dựng một persona subsystem mới.

Workflow worker có per-call provider/model nhưng dispose child sau một request,
vì vậy không được dùng làm runtime của spawn.

### Persona normalization và tool semantics

DSH `tools.restrict()` vẫn là seam dùng để giới hạn child, nhưng dsh-ecc không
áp dụng nó cho bundled ECC persona. `PersonaNormalizer` tạo runtime definition
từ frontmatter đã bỏ `tools` và `model`; body vẫn được truyền vào
`request.persona`.

Khi không có `toolFilter`, DSH compose child từ parent. Child kế thừa effective
tool scope và các restriction của parent/host; normalizer không grant thêm tool
và không mở MCP server mới. Continuable in-process child vẫn nhận native
contribution như `report` nếu host đã mount contribution đó.

Persona body được truyền vào `request.persona`. DSH đặt nó ở child-scoped
`deployment:persona` section, nên nó shadow deployment persona cùng tên của
parent; parent presets và `subagent:delegation` context vẫn được compose. Đây là
native replacement semantics, không phải additive append. Additive mode cần một
section/setup riêng và được để cho phase sau.

### 3.1 Fork provider cho `spawn_fork`

DSH `subagent-fork-in-process` đăng ký provider name `fork`. Provider có
`inheritsParentContext = true`; `start` và `prepareContinuable` tạo seed từ
completed parent turns (các event tới `turn/end`) và loại trừ turn đang chạy.
Vì vậy dsh-ecc có thể gọi trực tiếp `ctx.subagents.startContinuable` với
`provider: "fork"` thay vì gọi model-facing tool `subagent_fork`.

`prepareContinuable` có caveat upstream về việc ghép fork seed với prefix của
continuable setup/report. Adapter giữ feature này trong `spawn_fork`, dùng binding
store riêng và kiểm thử context inheritance + follow-up; không sửa DSH core.
Nếu host không mount provider `fork`, kết quả phải là
`TRANSPORT_UNAVAILABLE`, không fallback sang `spawn`.

## 4. Skills và invocation

DSH filesystem skill provider có các root mặc định .dsh/skills, .agents/skills,
DSH home, agents home và custom dirs. ECC root có
ECC/skills/<name>/SKILL.md, nên adapter có thể:

1. đăng ký một EccSkillProvider riêng qua ctx.skills.registerProvider, hoặc
2. cấu hình customSkillDirs nếu composition đã mount official filesystem
   provider.

Thiết kế chọn phương án (1) để ECC namespace, collision policy và alias được
kiểm soát bởi plugin, không cần sửa settings của DSH.

DSH tool-skill kiểm tra skill name, inject catalog vào prompt và hỗ trợ user
invocation dạng /<name>. DSH name validation không phù hợp với chuỗi có dấu hai
chấm như /ecc:<name>. Adapter vì vậy dùng tên canonical <name> nội bộ và cài
namespace pre-step `/ecc:<name>` do chính adapter resolve. Dsh-ecc không đăng ký
plain `/name`; native/project provider tự quyết định entrypoint đó.

## 5. Repo tham chiếu

### dsh-background-agents

Repo này chứng minh lifecycle production-like: start bằng
ctx.subagents.startContinuable, follow-up bằng ctx.subagents.followup, stop
bằng interrupt và catalog/persistence cho child. Tool background_agent hiện đã có
persona per-call và tool_filter; nó không cung cấp per-call LLM route/effort,
nên dsh-ecc lấy lifecycle/persona seam nhưng vẫn phải bổ sung route + effort.

### dsh-agent-teams

Repo này chứng minh cách bridge selection vào continuable runtime:
registerContinuableSetup, pending selection theo parent/label, cold-resume
descriptor, installModelSelection và generated child persona. Nó có team
orchestration, mailbox và UI nhưng các phần đó nằm ngoài MVP.

DSH tool-subagent cũng đã có persona ở config-level và backgroundMode
continuable; limitation của nó là persona/model/toolFilter cố định theo mỗi
tool instance, không phải selector động per-call. Workflow agent() chỉ cho
label, phase, schema, provider, model và loại persona/effort; worker dispose
child sau một workflow run.

Cả hai repo là blueprint, không phải dependency bắt buộc. Khi copy/adapt code
phải giữ MIT attribution và kiểm tra license/version tại implementation.

## 6. Kết luận nghiên cứu

spawn phải kết hợp hai seam khác nhau:

1. Workflow-style route validation: explicit LLM provider/model và effort có
   điều kiện được resolve qua DSH LLM runtime.
2. Subagent-style continuation: child luôn được tạo bằng startContinuable, route
   snapshot được re-install trong cold resume, còn persona được DSH descriptor
   persist từ request; tool scope do DSH compose từ parent.

3. ECC persona: body đã normalize được truyền trực tiếp vào request; provider,
   model và effort đến từ input explicit; không gọi lồng workflow.agent hoặc
   tool-subagent.