dsh-compact-and-branch

Readme

# 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:

```bash
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

```bash
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.

[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)