Skip to content

refactor: split the Host's subagent and tool modules along their seams - #428

Merged
Grivn merged 8 commits into
mainfrom
claude/host-module-splits
Oct 17, 2026
Merged

refactor: split the Host's subagent and tool modules along their seams#428
Grivn merged 8 commits into
mainfrom
claude/host-module-splits

Conversation

@Grivn

@Grivn Grivn commented Oct 17, 2026

Copy link
Copy Markdown
Collaborator

摘要 / Summary

把 Host 的两个过大模块按已有的接缝拆开，只搬移代码：subagent.ts（2,378 行）拆出提示词与人设、DSH 输出 schema 校验、回执恢复、归档目标、运行时容量工作流与项目档案归档工作流 6 个模块，仍作为对外的门面导出原有名称；tools.ts 中 439 行的 registerTools 按工具族拆成 5 个注册函数，注册顺序不变。搬移前先用测试固定了每种委托子 Agent 的人设、完成协议与任务文本以及全部工具卡片的哈希；用户和模型看到的内容不变。

Two oversized Host modules split along their seams by moving code verbatim: subagent.ts (2,378 lines) gives its prompts and personas, the DSH output-schema check, receipt recovery, the archive destinations, the runtime-capacity workflow and the Document archive workflow six modules of their own and stays the facade with the same exports; tools.ts's 439-line registerTools becomes five family functions registering in the same order. Before anything moved, tests pinned the hash of every delegated child's persona, completion protocol and task and of every tool card. Nothing users or the model see changes.

关联 Issue 或背景 / Related Issue or Context

Item H2 of the technical-debt review after v0.5.31 (#413).

涉及区域 / Affected Areas

  • Host 激活、Headless 或 bundle / Host activation, Headless, or bundle
  • 运行时记忆 / Runtime Memory
  • 项目档案 / Project Documents
  • 记忆空间或 Provider / Memory Spaces or Providers
  • 子 Agent 或 Agent 工作流 / Subagent or Agent workflow
  • Web UI 或对话交互 / Web UI or conversation interaction
  • 设置、存储或安全 / Settings, storage, or security
  • CLI、RPC、命令或工具 / CLI, RPC, commands, or tools
  • 安装、更新或发布 / Installation, update, or release
  • 测试、构建或文档 / Tests, build, or documentation
  • 其他（请说明）/ Other (explain below)

PR 类型 / PR Type

  • 面向用户的功能或行为变更 / User-facing feature or behavior change
  • Bug 修复 / Bug fix
  • 增强或优化 / Enhancement or optimization
  • 兼容性适配 / Compatibility change
  • 维护或重构 / Maintenance or refactor
  • 测试或构建 / Tests or build

变更内容 / Changes

  • Pins first (0236a9e0, extended in ea19a2ec): tests/subagent.spec.ts drives all 9 delegated operations (20 children) through the coordinator and pins SHA-256 hashes of each persona (14), completion protocol (8) and task (18); a second test pins all 16 tool cards. The pins pass on the pre-move code and after every move.
  • src/host/subagent.ts (2,378 -> 1,068 lines; the coordinator 1,467 -> 836 lines, 60 -> 48 members): new subagent-prompts.ts, subagent-output-schema.ts, subagent-receipts.ts, archive-destinations.ts, runtime-capacity.ts, document-archive.ts. 13 private methods became functions taking what they used of this (the live counters and runtimeSource, or a DocumentWorkflowHost the coordinator builds with its methods bound). The facade exports the same 17 names.
  • src/host/tools.ts: registerTools (439 -> 8 lines) calls toolHelpers (the original closures, built once) and five family functions; the 16 registration blocks are byte-identical and in the same order.
  • Record docs/pr-assets/host-module-splits with harness scripts that reproduce all eight files from the base by line slices and listed substitutions, and a bundle comparison. Changeset: dsh-mnemon patch.

最新代码确认 / Latest Codebase Confirmation

  • 我已基于最新 main 分支开发，或在提交前已 rebase 或合并最新 main。 / I developed from the latest main, or rebased or merged the latest main before submitting.

同步命令 / Sync command:

git fetch origin main
git merge origin/main

Branched from a8c40265 (the head of #426); main bd70979f (#426) merged in bad852aa.

AI 编码披露 / AI Coding Disclosure

  • 完全 AI 编码：全部编程改动由 AI 产出，并由贡献者接受和审查。 / Fully AI-coded: AI produced all programming changes, which the contributor accepted and reviewed.
  • 部分 AI 辅助：AI 帮助编写或修改了部分内容。 / Partially AI-assisted: AI helped write or modify part of the change.
  • 未使用 AI 编码辅助。 / No AI coding assistance was used.

使用的 AI 模型 / AI model used: Claude Opus 5.5 (claude-opus-5-5)

使用的编码 Agent 工具 / Coding Agent tool used: Claude Code

仓库规范检查 / Repository Rules

  • 未修改 DSH 官方源码，未让 tsconfig 指向 DSH 源码 checkout，仅使用正式的 @deepseek-ai/* NPM 契约。 / I did not modify DSH source or point tsconfig at a DSH source checkout, and used only published @deepseek-ai/* NPM contracts.
  • Client 与 Host 边界仍以浏览器安全的 src/host/protocol.ts 为准，没有在两侧重复定义 wire DTO。 / The Client and Host boundary still uses browser-safe src/host/protocol.ts as the source for wire DTOs.
  • 持久化格式、RPC 权限、路径或凭据处理的变更包含兼容或拒绝路径、安全分析和相应测试。 / Changes to persistence formats, RPC authority, paths, or credentials include compatibility or rejection paths, security analysis, and tests.
  • 没有提交 token、密钥、私有记忆、未脱敏日志或生成的 lib/ 文件。 / I did not commit tokens, credentials, private memory, unredacted logs, or generated lib/ files.
  • 用户可见文案和长期文档已同步维护中文与英文版本，命令、配置键和路径保持一致。 / User-facing copy and long-lived documentation are synchronized in Chinese and English, with matching commands, configuration keys, and paths.
  • 会改变发布制品或其元数据的 PR 已添加 changeset；仅测试、CI 或站点文档变更可不添加。 / A PR that changes a published artifact or its metadata includes a changeset; test-only, CI-only, and site-documentation-only changes may omit one.
  • 新增和修改的代码、注释、文档、提交信息不含 emoji。 / New and modified code, comments, documentation, and commits contain no emoji.

兼容性与数据安全 / Compatibility and Data Safety

  • The model sees the same tool names, descriptions, input and output schemas (tests/fixtures/model-tools.json unchanged) and the same persona, protocol and task text for every child (the pins). Persisted formats (archive index text, cold paths, lineage), RPC behavior and error messages are unchanged.
  • lib/index.js changes only at module boundaries: the same 29 external imports in the same order, every module region in order, the 13 moved bodies identical after normalizing this; of the statements that run at load, only three pure constant constructions change relative order. Every other build output, lib/types included, is identical. No package entry, declaration or plugin changes, so no peer floor moves.

本地验证 / Local Validation

执行的命令 / Commands run:

pnpm run verify
MNEMON_CLI_PATH=/nonexistent/mnemon MNEMON_PLUGIN_VERIFY_CONCURRENCY=1 pnpm run verify:plugins
DSH_HOST_ROOT=<DSH 0.2.0-rc.2> pnpm run test:installed-dsh
DSH_HOST_ROOT=<DSH 0.2.1-rc.2> pnpm exec vitest run --config scripts/installed-dsh.config.ts
node scripts/verify-sync-git.mjs
python3 docs/pr-assets/host-module-splits/harness/split-subagent.py ...   # reproduces the files from the base

结果摘要 / Result summary:

  • On the merged tree: verify passed (root tests 2,111 passed, 7 skipped in 152 files; plugins 593 passed, 3 skipped; package); verify:plugins passed; installed DSH 0.2.0-rc.2: 2,108 passed, 10 skipped; installed 0.2.1-rc.2: 2,111 passed, 7 skipped; Git sync 64/64; release:intent covers dsh-mnemon. After the pin extension: the subagent, tool-card and memory-tools specs (157), typecheck, the root tests (2,111 passed) and verify:docs pass.
  • An independent review reran the harness on both bases (all eight files byte for byte), compared every moved method for this binding, live state, await and error boundaries, confirmed no test spies on or replaces coordinator methods, rebuilt both sides (only module boundaries and three pure constants differ), checked the facade's 17 exports, and found that 40 of 42 one-character prompt mutations failed the pins. It found no must- or should-fix; its two nits (the reconcile child and two list separators were not pinned) are fixed in ea19a2ec, and the extended pins pass on the pre-move code.

用户可见变更证据 / Local Feature Evidence

证据 / Evidence: N/A, nothing users or the model see changes; the record has the harness, the pins and the bundle comparison.

🤖 Generated with Claude Code

Grivn and others added 8 commits October 18, 2026 00:41
@Grivn @claude
test: pin what delegated children read and the memory tool cards
0236a9e 
Before the Host's subagent and tool modules are split, pin the text they
give the model and the people using it, so the move can be checked
against the same values:

- every kind of delegated child, the eight write operations, the answer,
  placement, metadata, the four idle reviews, both MEMORY.md routing
  batches, the USER.md compaction and the document archive, reads the
  same persona, completion protocol (its result schema) and task, pinned
  as SHA-256 hashes with the run's requestId left out;
- every memory tool shows the same call and result cards, in
  registration order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
refactor(host): split subagent.ts into its prompts, receipts and arch…
5a5c16c 
…ive workflows

src/host/subagent.ts held the delegated children's personas, their result
schemas and the text of their tasks, the DSH output-schema check, receipt
recovery, and the runtime-capacity and Document archive workflows beside
the coordinator. Each now has a module of its own:

- subagent-prompts.ts: every persona, result schema and task-text helper;
- subagent-output-schema.ts: the DSH output-schema subset and its check;
- subagent-receipts.ts: reading a child's result, tool receipts and
  failure detail back;
- archive-destinations.ts: which Memory Spaces can take an archive, and
  the lineage a Provider's receipt proves, which both workflows share;
- runtime-capacity.ts: runtimeLocked, compactUserAndCommit,
  archiveRuntimeEntry, archiveRuntimeLocally, runtimeArchiveSource and
  the routing batches;
- document-archive.ts: the Document capacity and archive workflow.

The code moved verbatim. The class methods that left became functions
taking what they used of the coordinator: the counters, the runtime
source, or for the Document workflow a small host object the coordinator
builds with its own lookups and delegate. subagent.ts stays the facade
and exports the same names. The pinned persona, schema and task hashes
of every delegated child are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
refactor(host): register the memory tools one family at a time
4b4de31 
registerTools in src/host/tools.ts was one 439-line function that built
the helpers every tool shares and registered all sixteen tools. The
helpers now come from toolHelpers, and each tool family registers in a
function of its own: the View tools, Memory Spaces' reads, the Documents
tools, the runtime memory tool and Memory Spaces' writes, called in that
order, which is the order the model has always been given the tools.

Every registration block moved unchanged, the helpers are built once as
before, and the captured config is read at registration as before. The
model-tools fixture, the tool table and the pinned tool cards pass
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
Merge remote-tracking branch 'origin/main' into claude/host-module-sp…
bad852a 
…lits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
docs(pr-assets): record the Host module splits
c92b458 
The record lists what moved where with line counts before and after,
how the code moved, and three equivalence checks: the pinned text every
delegated child reads and the tool cards, the code lines before and
after with the split scripts that reproduce both moves from the
baseline, and the built Host bundle, whose statements match main's but
for the coordinator class, its former methods and the tool registration
functions, which are made of the old code. A changeset records the
patch for dsh-mnemon.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
test: pin the reconciliation child and the separators of a task's lists
ea19a2e 
The pins of what delegated children read covered eight of the nine
delegated operations: reconciliation, which runs through the maintenance
task runner, now has its child pinned too, over evidence with another
installation's entry, branches, documents, the sync branch's side and a
reviewer's opinion.

Every list in the pinned tasks had one element and no request field was
an object, so the separators that join them were never pinned. The
remember request now has two tags and an object field, the routed entry
two branches and the archived document two source paths.

The updated pins pass on the code before the move (a8c4026) as after it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn @claude
docs(pr-assets): record the extended pins of the Host module splits
7952038 
The record now counts 20 pinned children, the reconciliation child
among them, 14 personas, 8 completion protocols and 18 tasks, says that
the task separators are pinned, and that the extended pins pass on the
code before the move as after it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Grivn
Merge remote-tracking branch 'origin/main' into claude/host-module-sp…
2010c5c 
…lits

# Conflicts:
#	docs/pr-assets/README.md
@Grivn
Grivn merged commit 44a3cfc into main Oct 17, 2026
6 checks passed
@Grivn
Grivn deleted the claude/host-module-splits branch October 17, 2026 18:11
@Grivn Grivn mentioned this pull request Oct 17, 2026
Merged
11 of 28 tasks
LoveDoLove pushed a commit to LoveDoLove-Forked-Projects/dsh-mnemon that referenced this pull request Oct 18, 2026
@Grivn @claude
Merge origin/main 44a3cfc into claude/webui-gallery-embedding
6331c13 
Brings in omdsh-dev#428. The records index conflicted on its top row: both rows
are kept, this branch's gallery record first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@Grivn