dsh-turn-fold

Readme

---
description: "Install and configure two-level reasoning and tool folding in a DeepSeek Harness Web profile."
kind: "package-bundle"
---

# dsh-turn-fold

English | [中文](README.zh.md)

## Summary

This optional Web plugin groups reasoning and tool calls into collapsible steps. Completed turns collapse their process while keeping the final reply visible. It installs as a local profile layer and includes English and Chinese settings. It targets DeepSeek Harness `0.1.5-alpha.1`.

## Table of Contents

- [Use this package](#use-this-package)
- [Understand the implementation](#understand-the-implementation)
- [Further Exploration](#further-exploration)
- [Model Experience](#model-experience)
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
- [Dev Note](#dev-note)

-----

<a id="use-this-package"></a>
## Use this package

Install into an existing Web profile with the matching DSH version. Source development requires the parent repository's installed dependencies and built Web and CLI artifacts, with Node `^22.19.0 || >=24.0.0`.

### Install the local build

From the DeepSeek Harness repository root:

```sh
cd dsh-turn-fold
npm run dev:link
npm run build
dsh plugin --profile web add "$PWD" --offline
```

The link command only creates development symlinks inside this package. The install command adds the local package and activates its bundle layer in the selected profile. Refresh the running Web page after installation. Replace `web` when using a different Web profile.

Remove the layer with:

```sh
dsh plugin --profile web remove dsh-turn-fold
```

### Read a conversation

- While a reply streams, consecutive reasoning and tool calls share a collapsed step bar. Text remains visible between steps.
- When a turn finishes with a final reply, its process collapses into one bar. Click that bar to reveal the steps, then click a step to reveal the original reasoning and tool cards.
- Summaries show native tool-type icons, filenames, and counts of reads, edits, searches, commands, other tools, and failures. Active steps show the current tool or a short reasoning preview. Click a filename to copy its full workspace path without changing the fold state; a tooltip shows the path. Clipboard failures expose a selectable path for manual copying.
- Successful edits show added and removed lines from the tool's persisted diff metadata, excluding unchanged context. Multiple hunks and calls accumulate per file. Failed or unfinished edits and tools without diffs have no line totals. Three filenames fit in the initial summary; a separate disclosure exposes the rest. Matching basenames display their paths to distinguish them.
- Expand, collapse, and live content growth use height and opacity transitions. Quick reversals keep the displayed height, and automatic folding preserves keyboard focus. Fully collapsed rows contribute no message spacing, including after reloading or returning to a saved session. The system's reduced motion preference disables animation.
- Unanswered questions, human messages, and error rows remain visible. A turn without a known opening or final reply stays expanded by default.

### Change defaults

Open **Settings → Plugins** and click **Conversation folding** to expand its card. Folding behavior and process metrics appear in two sections inside the card; changes save immediately. Folding, automatic step collapse, automatic completed-turn collapse, and the metrics master switch start enabled. Duration, first-token time, token usage, generation speed, cache hit rate, and step count each have an independent switch, enabled by default. Turning the master switch off preserves those choices.

Step and turn disclosures use arrows: right when collapsed, down when expanded, and highlighted while running. The Host saves preferences across refreshes. Explicit disclosure choices take precedence for the current Session binding; refresh resets them. Disabling the plugin restores the native fold state captured when it took control.

Duration, first-token latency, generation speed, token usage, cache hit rate, and actual execution-step counts are restored from recorded Session events. Speed uses output tokens divided by the recorded decoding time; it excludes tool execution time. Missing timing or incomplete provider accounting stays hidden.

**Save process metrics locally** is enabled by default and independent of the display switches. DSH stores numeric checkpoints under `<DSH_HOME>/storages/session_projcache/`, so completed-turn metrics can be restored after a browser or Host restart and from another browser connected to the same Host. Turning saving off unregisters the plugin's checkpoint contribution and stops saving new plugin metrics. Displayed values can still be recovered from existing Session logs; this switch does not disable DSH's own chat logging. The switch itself is saved in `<DSH_HOME>/settings.yaml`.

A release notice summarizes the installed version. Dismissing it records that version in Host preferences, so it stays hidden across refreshes and other browser connections to the same Host. It performs no network update check or plugin installation.

-----

<a id="understand-the-implementation"></a>
## Understand the implementation

<details>
<summary>Implementation and verification — click to expand</summary>

The [bundle patch](cordis.patch.yml) inserts one Host plugin. The [Host entry](src/index.ts) registers the `turn-fold` settings namespace; the [browser entry](src/client/index.ts) provides Session hooks, localized settings, and reversible renderer decoration. The manifest restricts the client to Web.

The [projection](src/client/projection.ts) reads existing Chat nodes and groups them within each turn. The [Session model](src/client/session.ts) coalesces node and metric updates and recalculates affected turns. The [recorded-metric fold](src/metrics.ts) is shared by a Conversation contribution and the optional Host checkpoint, so both use the same durable timestamps. The [renderer adapter](src/client/decorate.ts) preserves existing injection, child slots, and renderer chains; it controls the native reasoning presentation through the original owner props. No second history subscription is opened.

[File summaries](src/client/tool-summary.ts) validate opaque result metadata and use the bundled `diff` library to count hunk operations. Tool icons come from DSH primitives; disclosure arrows use inline SVG. Step-bar text shares a line height, with icon groups aligned to the text line so failure counts and live previews remain level with tool counts. [Animated regions](src/client/Collapse.tsx) retain original children through exit transitions, observe live size changes, and release their observers and animations on disposal.

No runtime invariant companion is published: the plugin owns a derived presentation and ephemeral viewing choices, without an independently authoritative persisted relation to compare. Behavior tests cover the projection, subscription disposal, renderer restoration, and real Web composition.

Run the following from this package in the source checkout:

```sh
npm run verify
npm run test:browser
npm run test:install
npm run docs:check
```

The browser check launches a temporary DSH profile, replays recorded read, edit, and failed-search sessions, and compares conversation and settings accessibility snapshots. It checks clipboard copying, saved preferences, release acknowledgement, motion, mobile layout, summary text alignment, language changes, and native fold restoration. The installation check adds and removes the package through the official CLI in another temporary profile. Both checks clean up their temporary homes. After editing a bilingual document pair, review both languages and run `npm run docs:record`.

</details>

-----

<a id="further-exploration"></a>
## Further Exploration

- [Design decision](.agents/notes/implemented/architecture/2026-09-08-two-level-folding.md) explains rendering ownership and compatibility costs.
- [Winter-And-You-Gone/dsh-turn-fold](https://github.com/Winter-And-You-Gone/dsh-turn-fold) is the feature reference for step and turn folding. This package implements those interactions for the local DSH version.

-----

<a id="model-experience"></a>
## Model Experience

None. Folding changes browser presentation only. It adds no model input, tool, Session event, or KV-cache effect.

<a id="known-limitations-and-deferred-work"></a>
## Known Limitations and Deferred Work

The renderer adapter depends on the current Chat registry and requires verification when upgrading DSH. Grouping covers loaded history; loading earlier rows can reveal an opening that makes a turn eligible for folding. Hidden tool bodies must be expanded before using browser text search inside them. Compatibility with third-party plugins that replace renderers without delegating is unverified. Full paths require Session workspace metadata; without it, relative paths remain as recorded. Diff totals describe applied operations, not the final working-tree diff; incomplete or unsupported tool metadata cannot supply missing totals.

<a id="dev-note"></a>
### Dev Note

<details>
<summary>Working context for maintainers — click to expand</summary>

None.

</details>