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 (the durable modelSelection projection, falling back to the latest request header and then the deployment default).
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 Host sessionController.create API, with the source workspace, active preset, and no parentSession fork lineage, then inherits the model route via sessionController.selectModel, which durably records a model/selection event for the next request.
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 the session 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.3.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

This release (0.3.x) targets DSH ^0.1.5-rc.2 and is a clean break from the 0.1.1 line. DSH 0.1.5 removed the entire Host API-Proxy surface this plugin's host half was built on (ctx.apiProxy.* moved onto owning business services, notably ctx.sessionController) and retired the @deepseek-ai/dsh-client-runtime package the browser half injected, so a single package cannot serve both lines: the peer sets are disjoint. Users on DSH 0.1.1-rc.x should pin #v0.2.0.

Within a line the plugin is deliberately resilient where it can be: unknown ManualCompactionError codes fail open to a raw error instead of a misleading message, and the DSH surfaces it rides (the compaction seam, the session event vocabulary, the projection registry) have been stable across releases. Three documented internal reliances remain and are guarded loudly at runtime: the idle turn-cursor advance on the created Agent (agent.phase became the public field after setPhase went private), the maxTokens carry-over onto the target AgentOptions, and the filtering of system-role messages out of the imported continuation (DSH 0.1.5 added the system-prompt projection to deriveMessages(); the fresh session rebuilds its own system context, so the source's is dropped rather than duplicated). A DSH update that breaks any of these degrades to a visible initialization error, never silent history corruption.

Presentation-side, the client half rides three 0.1.5 wire shapes that are contracts of the DSH client packages rather than this plugin: the session-list row's projectionValues field (where the navigation projection's view value arrives — misnamed reads here fail as "no navigation", silently), the agentPreset session-projection value on the host list summary (0.1.5 moved it off the summary field; the handoff reads it through the projections so preset inheritance survives), and the command card's collapsed-summary rendering rule (one line is clamped; multi-line text becomes an expandable body, which is why every outcome text this plugin emits is deliberately two lines).

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. The command card and the fresh session both render the compaction summary through DSH's own MarkdownText renderer — the same fully-formatted, in-document-flow presentation /compact uses — via the conversation.chat.commandview and conversation.chat.turnTail UI slots. In the fresh session, the imported history is collapsed behind a native DSH notice row, leaving only live conversation visible plus the formatted summary card at the end of the imported turn. On shells without the react/@deepseek-ai/dsh-client-ui-primitives module seed words or the slots service, the plugin falls back to the native bounded context row for the imported checkpoint.

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.