dsh-compact-and-branch: /compact-and-branch

A focused out-of-tree DeepSeek Harness plugin for treating canonical context compaction as a clean session branch point.

Motivation

Long-running coding-agent sessions can accumulate a great deal of useful working context before reaching a natural phase boundary. DSH's /compact command is useful for reducing that history while preserving the state needed to continue, but sometimes it is preferable to make that compaction a clean branch point: continue from the resulting state in a fresh session while leaving the compacted source session independently resumable.

This is especially useful with relatively limited context windows, as is common with local LLMs, where long agent trajectories can otherwise require repeated compactions and make session boundaries more consequential.

/compact-and-branch is intended to have essentially the same model-facing effect as running /compact and continuing normally in the original session, except that the continuation occurs in a new root session. It deliberately reuses DSH's canonical compaction result rather than introducing a separate handoff summary or another lossy transformation of the session state.

What it does

/compact-and-branch:

1. Preflights the source session's workspace, active preset, and current model selection.
2. Calls the same operation as built-in /compact: ctx.compaction.compactNow(invocation.agent, invocation.signal, invocation.commandId).
3. Only after that succeeds, snapshots source.session.deriveMessages(). This is the canonical checkpoint message plus the complete retained recent tail; the plugin never reads or rewrites CompactionResult.summary.
4. Creates a new root session through the supported Host session.create API, with the source workspace, active preset, provider/model/reasoning effort, and no parentSession fork lineage.
5. Adds one minimal preamble followed by exact copies of every canonical post-compaction message, preserving message content, ordering, roles, identities, provenance, and tool pairs. It then advances the new agent's idle turn cursor past the imported turn so the first live response receives a distinct turn/step identity, and assigns a pinned handoff title.
6. Flushes the target, then publishes a typed session projection. The browser half waits for the target to appear in sessions.list, refreshes the list to replace its provisional blank-session row with the persisted populated summary, and calls the supported ctx.sessions.open(targetId) API.
7. In the fresh session's chat presentation, hides the synthetic imported turn's checkpoint and retained recent-tail rows, leaving its native, selectable DSH notice row: “Compacted context imported from previous session.” The notice keeps the project's standard context typography, color, disclosure behavior, and accessibility; durable model-facing messages remain unchanged.

Built-in /compact is not registered, shadowed, or modified.

Install

dsh plugin is a thin pnpm forwarder: it runs pnpm inside your profile directory and then reconciles the profile's dsh.profile.bundles stack for you, so no hand-editing of any config file is needed. Install the plugin from GitHub:

dsh plugin --profile web add git+https://github.com/zeropointnine/dsh-compact-and-branch

# or pin a release tag
dsh plugin --profile web add github:zeropointnine/dsh-compact-and-branch#v0.2.0

A first dsh plugin run in a profile initializes it automatically. The profile's package.json gains the dependency, and DSH appends dsh-compact-and-branch to dsh.profile.bundles on its own (it detects the package's dsh.bundle declaration). This package has no build or install scripts, so git-hosted installs need no allowBuilds entry in the profile's pnpm-workspace.yaml.

After adding, restarting, updating, or removing the plugin, restart DSH. To remove it later: dsh plugin --profile web remove dsh-compact-and-branch.

Compatibility

The peer ranges (^0.1.1-rc.2 for the @deepseek-ai/dsh-* packages) reflect the DSH release line this plugin was written against. It relies on DSH's canonical compaction, session, projection, and Host API surfaces of that line; check the peer ranges when DSH ships a new major/minor release.

Usage

In any session, type:

/compact-and-branch

No arguments. The current session is compacted through DSH's canonical /compact machinery, then a fresh root session is created in the same workspace and preset with the same model selection, carrying the compacted context; DSH opens it in the browser. The compacted source session stays independently resumable. In the fresh session, the imported history is collapsed behind a native DSH notice row, leaving only live conversation visible.

Development

pnpm install   # installs the @deepseek-ai/* peer copies and zod
pnpm test      # node --test

The tests load host-side classes (Session, ManualCompactionError, message creators) from a separate module instance than the plugin's own imports, to exercise the cross-package error-classification boundary. They resolve that instance from the DSH_HOME environment variable (point it at a DSH checkout's node_modules/@deepseek-ai directory, or the checkout root) and fall back to the package's own pnpm-installed peer copies; if neither is available, those tests skip with a hint instead of failing.