dsh-conversation-tree

Readme

# dsh-conversation-tree

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

A DSH Web plugin for immutable conversation branches and message-level tree browsing:

- **Regenerate**: create a child session immediately before the selected turn
  and replay all human messages from that turn in their original order, including
  later steering instructions and attachments. Hidden runtime context is excluded.
- **Edit a prompt**: the original user bubble becomes a compact inline editor,
  prefilled with its text and a model selector—no modal. Saving preserves its
  non-text attachments, replaces only the first human message, retains later
  steering messages unchanged, and continues in a new child session. The action remains
  available after generation is manually stopped, including interrupted steps
  that never receive a `turn/end` event.
- **Edit a reply**: the original assistant message becomes the same inline
  editor. Saving copies through the selected turn and replaces the last reply
  in a child session without calling the model.
- **Inline switching**: show `‹ 2 / 5 ›` beside any branched user message or
  assistant reply. In the assistant action row, the switcher sits immediately
  after DSH's native create-branch action.
- **Message tree**: shared history appears once, while edited prompts and
  regenerated or edited replies fork at the exact message they replace. Select
  any message path to open its backing session.
- **One logical conversation**: branches created by this plugin collapse to one
  sidebar row. Switching plugin branches changes which version that row opens,
  while DSH's native **Fork Session** continues to create a separate sidebar
  conversation.
- **Live continuation**: sending a follow-up from any branch updates the current
  chat immediately; completing a normal turn does not require a page refresh.

Each immutable branch is still stored as a physical child session so no source
history is rewritten. This is an implementation detail: a durable provenance
marker limits the client-only sidebar projection to plugin-created branches. It
does not archive or delete any version, and native Fork sessions remain visible
even when forked from a plugin branch. Every plugin branch remains available
through inline switching and the tree. Child sessions record
`parentSession`, inherit the source working directory and preset, and adopt the
provider, model, and default reasoning effort selected in the inline editor.
Regenerate uses the current session selection. Neither path reuses the
historical target turn's model settings or changes the source session.
Branch creation does not change the host default model. On DSH 0.1.2-rc.1,
the plugin temporarily wraps `agentDefaultModel.saveSelection` and uses
Node async-local scope to suppress only the branch selection's default save.
The native session selection, picker, reasoning effort, and subsequent ordinary
model switches keep their normal behavior; concurrent ordinary saves still run.
The wrapper is removed after the operation, including failures, without replacing
a later wrapper installed by another plugin. Hosts without this service interface
report a model-selection error. This integration is verified against DSH 0.1.2-rc.1.

Branches created by v0.4.3 or earlier have no provenance marker. After updating,
those existing branches are shown as separate sidebar sessions; new plugin
branches collapse normally. No migration or session-log rewrite is performed.

## Requirements

- DSH `0.1.2-rc.1`
- A Web profile (`web` in the examples below)

Version `0.6.0` migrates to DSH's Session Controller, durable model-selection projection, and `uiConversation.events` browser interface. Live history is read through event snapshots; child sessions record the inherited event count separately from their header, preserving branch navigation after a restart. This version requires DSH `0.1.2-rc.1`; keep plugin `0.5.1` on older DSH installations. The browser reads chat content through `useChat` and projects a separate visibility mask over the read-only workspace source. Cold seeded-session summaries omit custom projections in this DSH version, so the plugin resolves missing branch ownership with bounded read-only inspection. It does not resume sessions or rewrite existing history.

## Install

```sh
dsh plugin --profile web add github:Unintendedz/dsh-conversation-tree#v0.6.0
```

Restart the running DSH Web service. In a completed conversation, edit actions
appear below their messages; selecting one replaces that exact message with a
prefilled inline editor and model selector. Regenerate remains below the
assistant reply. Messages with multiple versions receive an inline branch
counter after the native create-branch action. The **Tree** tab remains
available for browsing the complete message tree.

## Update

Install the new tag, then restart the service:

```sh
dsh plugin --profile web add github:Unintendedz/dsh-conversation-tree#v0.6.0
```

## Uninstall

```sh
dsh plugin --profile web remove dsh-conversation-tree
```

## Development

```sh
npm install
npm run build
npm test
```

Set `DSH_NATIVE_ROOT` to the installed DSH package root containing its `node_modules` to include native Session, Inbox, Session Controller, and Cordis integration tests. Use a fresh temporary `DSH_HOME`; these tests load package code with synthetic data and do not boot an existing profile.

The host entry point is `lib/index.js`; browser sources live in
`src/client.jsx` and `src/tree.js`. `npm run build` uses the pinned esbuild
version to generate `lib/client.js`.

The tree view reconstructs each durable fork from the child session's parent,
seed, and conversation events. Linear history stays in one lane; indentation
increases only at real fork points, so long conversations remain readable.
Ordinary sessions are included and DSH subagent sessions are deliberately
excluded. Broken parent links and cycles are bounded instead of blocking the
page.