Replace outdated references to 'DeepSeek Code' with the correct
product name 'DeepSeek Harness SDK'. Update demo commands to
reflect the SDK nature (demo:agent, demo:acp) rather than the
old coding-agent product.
Codex review of the vocabulary relocation found two doc-accuracy issues:
- presentation.ts's JSDoc used {@link ToolDefinition...}, which the
TypeScript language service cannot resolve because presentation.ts
deliberately does not import index.ts (that would create the cycle the
split avoids). Demote those three to plain `ToolDefinition` code text;
same-file and imported @links (TerminalResultView, ContentBlock) stay.
- docs/core-data-structures/tools.md's source header listed only index.ts
and schema.ts; add presentation.ts, which now owns the presentation
vocabulary the page documents.
The tool render-intent vocabulary (ToolCallView/ToolResultView + members,
FileLocation, FileDiff, ToolCallKind) is the UI-facing surface of
dsh-tools; it lived inline in index.ts alongside the registry and
execution core. Move it to its own presentation.ts module so index.ts is
the registry + execute waterfall and the presentation vocabulary is a
separate, one-directional dependency.
presentation.ts owns ONLY render-intent types and references none of the
execution types; index.ts imports the view types for ToolDefinition's
presentCall/presentResult signatures (clean acyclic index -> presentation).
The opaque `meta` presentation channel (ToolExecuteReturn, ToolResult,
ToolExecutionResult) is execution plumbing and stays in index.ts.
Public surface unchanged: index.ts re-exports the vocabulary, so consumers
(tool-fs/tool-bash/tool-web/tool-todo, the ACP bridge) keep importing from
@deepseek-ai/dsh-tools with zero churn. No producer/bridge/test edits; a
pure internal relocation with no observable-output change (snapshot goldens
untouched).
The result-time diff card sent view.title raw, so a completed edit/write
of an absolute in-workspace path flipped the card header back from the
relativized `Edit src/b.ts` to the absolute path — the pending card
relativizes, the result did not, and tool_call_update.title replaces the
header. Apply displayTitle to the result diff arm using the diff path,
mirroring the call-side card. Regression test proven red on the unfixed
arm.
Also record the overwrite diff-basis pre-read as a bounded follow-up
(TODO(overwrite-diff-bound) + RFC non-goal): overwriting a large file
reads the whole prior text into memory for a UI-only diff.
master's web_search/web_fetch tools were authored against the old
ToolCallPresentation bag; the render-intent union replaces it with a
card-tagged discriminated union. Both are simple generic cards, so they
declare card:'generic' explicitly.
Redesign per review: neither language is canonical. A pair is three
sibling files — foo.md, foo.zh.md, foo.i18n.yaml — and either language
may be authored first (a Chinese-first RFC is as legitimate as an
English-first one). The sidecar record holds the FULL git blob hash of
both sides as of the last confirmed-consistent state, replacing the
in-file one-directional fingerprint; editing either side without
re-confirming the pair goes red. New --write mode re-records a pair
after both sides are brought in line, making the confirmation a
reviewable yaml diff. Pairs merge whole (completeness enforced).
- gate rewritten around pair anchors (union of .zh.md and .i18n.yaml
remnants) so half-deleted pairs are caught from either side; red/green
proven for en-only edit, zh-only edit, missing record, and a record
for an excluded file
- verify-rfc-classification now skips .zh.md counterparts (same RFC,
indexed via its English filename; the pairing gate owns consistency)
- docs/i18n/README.md + translation-rules.md reframed bidirectionally
(terminology table binds both directions; typography section governs
the Chinese side); zh counterparts updated; skill workflow updated
- RFC amended to the shipped design, records the English-canonical
in-file-fingerprint model as considered-and-revised; RFC translated
(docs/rfc/.../2026-07-02-bilingual-docs-and-pairing-gate.zh.md) and
added to the required frontier
- generated docs stay excluded with the follow-up recorded: teach the
generators to emit Chinese, then de-list
Three comments still implied the result diff is always an applied hunk or
that write returns undefined on no-hunk: the toolResultUpdate JSDoc (a diff
result "emits the applied-hunk blocks, which replace the call-time snippet"),
the empty-diffs test comment ("an empty write returns undefined" — write now
falls back to a whole-file diff), and diffsFromMeta's JSDoc ("a bad meta
yields no diff card" — only true for edit; write falls back to a whole-file
diff). Each now states the write whole-file fallback. Regenerate the catalog.
Codex's stale-prose pass found seven more spots still describing the
result diff as ALWAYS an applied contextual hunk, or a create/binary
overwrite as rendering "only the call-time card": the DiffCallView JSDoc
and the acp bridge diff-arm comment, the FsWriteOutcome.before and
readTextForDiff JSDoc, and three RFC lines. All now say: the result diff
is the applied change — a contextual hunk when there is a before-image,
else a whole-file diff (create / undiffable binary) — and a successful
mutation always returns the result diff so the model-facing text can't
clobber it. Regenerate the cordis catalog (source line shift).
The writeText comment still said a null `before` (a create or an
undiffable binary file) means "a consumer renders no result-time diff,
only the call-time whole-file card." That is stale since write's
presentResult renders a whole-file diff for a null before-image. Correct
it: a null `before` gives no contextual-hunk basis, so the consumer falls
back to a whole-file diff — the tool still renders a result diff card, not
the raw result text.
The acp README's presentResult card list still described the `diff` result
as always "the APPLIED hunks computed from before/after". Qualify it like
the other surfaces: typically the applied hunks, or a whole-file diff for a
create, and a successful mutation always returns it so the result text
can't clobber the diff.
The write-diff-card fix made write's presentResult return an args-derived
whole-file diff (oldText:null) for a create / unchanged overwrite, but the
DiffResultView contract and its mirrored docs still said `diffs` is ALWAYS
the applied contextual hunks computed from before/after. Correct the type
JSDoc, the write execute-side comment, and the four mirrored surfaces
(tools.md, tools README, acp-feature-support, adding-a-tool cookbook) to
say: typically the applied hunks, or a whole-file diff when there is no
before-image (a create) — and that a mutation returns the diff result even
when it duplicates the call-time card, since a tool_call_update.content
replace would otherwise clobber the diff with the model-facing text.
Regenerate the cordis catalog (source line shift).
A Write CREATE rendered its completed tool_call_update as the model-facing
result TEXT (`<path>…</path>…Created file`), which — because an ACP
tool_call_update.content REPLACES the call's content — clobbered the
new-file diff the pending call installed. So Zed showed the diff, then
replaced it with raw XML-ish text; only overwrite/edit looked right
(their result re-sends a diff).
write's presentResult now ALWAYS returns a diff card for a successful
write: the applied contextual hunk from `meta` when there is one
(overwrite), else an args-derived whole-file diff (`oldText: null`) for a
create or an unchanged-content overwrite. This matches claude-agent-acp,
where the create diff rides on the update and no result text replaces it.
An error still falls through to generic rendering so its message shows.
edit is unchanged (it always has a hunk; no whole-file fallback).
Re-recorded fs-write / fs-write-overwrite goldens; the create's completed
update is now a {type:'diff'} block, not the XML result text.
Same stale enumeration as the presenter-note fix, in the ToolPresenter
JSDoc: it said the tool/result event "carries only { callId, content,
isError }". The event also carries error and meta; the load-bearing fact
is that it omits the tool name/args (why the presenter remembers them per
callId). State that instead of an exhaustive list that drifts.
The pasted type-equiv block's JSDoc still said the meta payload is
`{@link JsonValue}`; the source comment is `unknown` (the meta channel is
opaque at the seam). verify-type-equiv compares type structure, not the
comment, so the drift slipped through — align the doc comment.
The callId→args map note said the tool/result event "carries only
{ callId, content, isError }" — an exhaustive field list that drifts as
the event grows (it also carries error, and now meta). State the load-
bearing fact instead: the event omits the tool name/args, which is why
the bridge remembers them per callId.
Address the applied-hunk-diffs review:
- CRLF write overwrite emitted bogus every-line-changed hunks: write's
`before` was LF-normalized but `after` kept the raw model content, so a
CRLF rewrite of an LF file diffed every line. Normalize write's `after`
to LF so both sides share the diff basis (edit already did). Regression
test proves it fails on the raw-after path.
- The tool-private `meta` payload is now typed `unknown` (opaque) at every
seam instead of `JsonValue`. This drops the `dsh-tools -> dsh-session`
package edge that existed only to name the type, and removes the
`FileDiff` index signature that had been widening the type solely for
JsonValue-assignability. Serializability is still enforced at runtime by
`Session.append`'s isJsonValue check, which was always the real guard.
- Sync the docs the new result/meta surface left stale: ToolResultView's
diff card + ToolExecutionResult.meta in tools.md/session.md type-equiv
blocks, the acp/tools READMEs, and the adding-a-tool cookbook; regenerate
the cordis catalog and module graph.
A four-way parallel review of every EN<->ZH pair (one reviewer per pair,
findings verified before applying) surfaced:
- terminology: stale-sense 过期 -> 陈旧 in development.zh.md (the table
reserves 过期 for expired); GitHub workflow -> GitHub 工作流 per the
table; dropped the invented 质量 in 'CI gates' -> CI 门禁; taxonomy ->
分类体系 in translation-rules.zh.md; skill first-occurrence annotation
added in the i18n README
- verbatim spans: <current-blob> restored inside an inline code span the
translation had localized
- typography: full-width dashes normalized to no surrounding spaces
across all four files (the rules' own MUST); one 顿号 between clauses
-> comma; 顿号 before 以及 dropped
- fidelity/wording: must-not rendered 不得 (not 不应); local setup ->
本地环境搭建; enforce -> 强制执行; verified surface -> 受验证的范围;
batch-lands-before-neighbors nuance restored; 更新粘贴内容
freshness -> 新鲜度 confirmed against MDN's zh HTTP caching docs (freshness
lifetime -> 新鲜度生命周期); precedent now cited in the table. The same
source pairs stale with 陈旧, not 过期 (过期 maps to expired), so the stale
entry and the i18n README translation now say 陈旧译文.
Every new term the bilingual-docs work introduced, with precedented
renderings where precedent exists:
- orphan -> 孤立 (git's official zh l10n renders orphan as 孤立, e.g.
孤立分支 — not 孤儿; the translations were corrected to match)
- info string -> 信息字符串 (CommonMark zh convention; corrected in the
i18n README translation)
- fenced code block -> 围栏代码块 (MDN zh), staged -> 暂存 (git zh),
event-sourced -> 事件溯源 (DDD convention), smoke test -> 冒烟测试,
fail-fast -> 快速失败, plus fingerprint/pairing/freshness/stale/contract
- mechanism names coined by this repo, marked as such in the notes:
language switcher -> 语言切换行, structural signature -> 结构签名,
enforcement frontier -> 强制边界
- keep-English entries so future translators don't guess: backlog,
blob hash, CI, doc-sync, e2e, monorepo, PR, worktree
fs write/edit now emit a result-time contextual-diff tool_call_update
(the applied hunk with ±3 context lines, one hunk per replace_all site),
matching what claude-agent-acp sends and what makes an editor render the
change in place. The call-time snippet diff stays; the result hunk
supersedes it (ACP content-replace).
Mechanism:
- A persisted tool-private `meta` channel: execute may return
`{ content, meta }`; `meta` (JsonValue) rides on the tool/result event
and is handed back to presentResult, so the diff reproduces on replay
(event-sourced). JsonValue is now exported from dsh-session.
- The backend returns raw before/after text (storage facts) on
FsWriteOutcome/FsEditOutcome; the tool computes the hunk via the npm
`diff` package's structuredPatch. A create has no before → no result
diff; a failed/aborted mutation carries no meta.
- ToolResultView gains a DiffResultView; the bridge's result-side switch
renders it as {type:'diff'} content blocks.
RFC: docs/rfc/implemented/architecture/2026-07-02-result-time-applied-hunk-diffs.md
(justifies the npm `diff` runtime dep over vendoring and the meta channel);
the render-intent-union RFC's Non-goal is updated to record this shipped.
All fs snapshot goldens re-recorded; edit/overwrite gain the contextual
result diff, create/read/policy-reject unchanged in structure.
Review findings addressed:
- The gate compared only heading and code-block COUNTS, understating the
contract it claims to enforce. It now compares ordered structural
signatures: heading depths, fenced code blocks verbatim (info string +
content), table column counts, list kinds, and every link target except
the language switcher. Proven red on a heading demotion, a reworded
code-block comment, and a retargeted link; green on all existing pairs.
- Stated the gate's limit explicitly (header comment + docs/i18n/README.md
both languages): green means fresh and structurally sound, NOT verified —
translation quality is the reviewer's half of the contract.
- first-line extraction no longer silently drops the last character of a
newline-less file (split with limit instead of indexOf slice).
- isExcluded documents the trailing-slash-is-the-boundary invariant.
- Rollout guidance: grow the required frontier at the pace translation
review is resourced.
- dsh-code-review's doc-sync sublist is now the exhaustive chain.
docs/i18n/README.zh.md updated via the minimal-diff workflow and
re-fingerprinted.
The numResults (exa) and searchRecency (perplexity) conditional spreads
in apply() were only exercised on their absent side, leaving the 100%
per-file branch gate red. Add plugin-registration tests that pass those
config fields and assert they reach the request body.
