dsh-session-tree
Append-only, multi-branch conversation trees for
DeepSeek-Harness — a
PI-Agent-style SessionTree. The agent's history becomes a tree of immutable
nodes, forkable at any historical node, with standard LLM message
reconstruction, versioned JSON snapshots, and a WebUI tree panel.
Published as four npm packages under the @robiteame scope:
Install (users)
One command — from the plugin market UI, or from a Harness checkout's CLI:
dsh plugin --profile <profile> add @robiteame/dsh-session-tree
Prebuilt tarballs install the same way and need no build scripts:
dsh plugin --profile <profile> add robiteame-dsh-session-tree-0.1.0.tgz
After installing, restart the profile. The composition gains three rows
(pi-agent-session-tree, tool-session-tree, ui-session-tree) that load the
Host service, the tool and commands, and the browser panel. Type /tree in the
composer to open the panel; click a node to bind it as the active context, then
/fork [branch] and /clone operate on that selection. /session reports
tree status (nodes/messages/branches/tokens/cost) and the active surface mode.
Verify the composed layer:
dsh --profile <profile> --dump-config # should list the three session-tree rows
Requires DeepSeek-Harness 0.1.2-alpha.3 (or a compatible 0.1.2 build) and
Cordis ^4.0.2; the target installation provides those peers. No install
scripts run — the tarballs ship prebuilt lib/ artifacts.
Branch switching and graceful degradation
The plugin never modifies Harness core files. It capability-detects the
optional branch-selection engine API at runtime:
- Native mode — on a checkout carrying
dev/session-branch-surface.patch
(Session.selectMessageSurface()), jump/fork switch the model-visible
history directly: the next turn genuinely starts from the new branch.
- Stock mode — on an unmodified official Harness, the plugin emulates the
switch through official append APIs (an empty
replace surface event) plus a
plugin-owned sidecar under $DSH_HOME/storages/session-tree/ for durable
branch state. The log stays resume-valid.
- Projection mode — if even the emulation is unavailable, navigation moves
the tree projection and panel only, and the next turn keeps the canonical
history.
Every mode is honest about itself: session_tree's context/session
operations and /tree outputs carry a surface field (native, stock, or
projection), and the Host log prints a one-time notice when a session runs in
a non-native mode. Move the raw session.jsonl.zstd between machines together
with the matching sidecar file, or carry the projection explicitly with
/tree snapshot save/load.
Semantics
- Append-only — every node is immutable; branching and jumping only move
the cursor. Old branches are never edited or deleted.
- Every entry is a node — messages, tool calls, model switches, compaction
records, branch summaries, and custom entries all become typed nodes
(
message, tool_call, model_change, compaction, branch_summary,
custom; tool_result survives only for orphan results with no matching
call); each has a unique nodeId and a parentId (root is null). A node
may have multiple children — that is the fork.
- One entry per tool interaction — a
tool/call and its tool/result fold
into a single tool_call node whose content carries both the call part and
the result part (isError plus the node's error mark failures), whether
the pair arrives in one event batch or across sync batches. Legacy snapshots
with split pairs fold on restore.
- Cursor navigation —
jump(nodeId) moves the active leaf to a historical
node; the next append grows a new branch from there. Sibling branches stay
intact. The durable Harness Session log remains the source of truth.
- LLM context —
context returns the standard messages array for the
root→cursor path only.
- Compaction — surface replacement is recorded as an immutable
compaction
node instead of pretending the shadowed messages were deleted.
- Snapshots —
snapshot.save/snapshot.load round-trip the whole tree as
versioned JSON (version: 1).
- Multiple trees — one independent tree per agent session.
- Errors — every operation answers
{ok: true, value} or
{ok: false, error: {code, message}}.
Development (contributors)
The repository is a pnpm workspace building the three implementation packages
standalone (no Harness checkout needed):
pnpm install
pnpm verify # build + typecheck (host & client) + pack dry-run + vitest
pnpm pack:all # produce the four tarballs
Tests run against the published Harness packages (0.1.2-alpha.3) — the
stock-mode paths — with vitest from the repository root. The browser spec in
packages/client/ui-session-tree needs the Harness client test runtime and
runs inside a source-integrated checkout.
Source integration against a Harness checkout
For debugging against Harness source (native mode, native details dock):
dev/install.sh /path/to/deepseek-harness # applies both dev patches + copies packages
cd /path/to/deepseek-harness && pnpm install && pnpm run build
See dev/README.md for what each patch does. This flow is
for contributors only — user installs never touch a Harness checkout.
License
MIT.
