dsh-session-handoff
Session handoff & context management for DeepSeek Harness — built because the
existing session-management and context-pruning plugins were written before
the latest DSH update and don't cover the full workflow.
Why
Long sessions (like a 170k-line r32 session) hit context limits, trigger
repeated automatic compaction, and stall. Switching to a fresh session loses
all progress. This plugin fixes both halves — and more:
- Handoff — export a structured, portable handoff document so a fresh
session can continue seamlessly.
- Active context pruning — compress spent history before the context
window fills (official compaction API, model-authored summaries).
- Session management — trash / restore / purge / list sessions.
- Model routes — every registered route (official API, Ark, custom,
vision-toolkit wrappers) is orderable and switchable; each route can pin
its own model and reasoning effort (
provider:model:effort), or follow
the chat's current selection. No model id is hard-coded.
- ACP thresholds — tune compaction limits without touching YAML.
Tools
Module A — Handoff (zero dependencies)
| Tool | Purpose |
|---|
handoff_status | Compact session overview: turns, messages, tool usage, checkpoints, context pressure |
handoff_export | Parse the session into a structured Markdown handoff under <workspace>/.dsh-handoff/ + a ready-to-run handoff package (OpenViking archive command, archify diagram command — only when those enhancers are present) |
handoff_resume | Load the latest handoff document in a fresh session and continue |
Also /handoff command.
Module B — Active Context Pruning (official compaction API)
| Tool | Purpose |
|---|
acp_status | Usage, surface seq map, limits (soft/hard pressure level) |
acp_compress | Replace an inclusive surface seq range with your summary (ctx.compaction.compactRegion) |
acp_decompress | Read the original text hidden by a checkpoint (read-only) |
acp_search | Search visible + hidden compacted history |
acp_config | Show the active thresholds (soft/hard limits, preserveRecent, minTokens, nudge) |
acp_set_limit | Persist new thresholds into settings.yaml (new sessions take them) |
Plus a system-prompt pressure banner that nudges the model to compress past
the soft/hard limit (60% / 70% defaults), and a compaction.summarize
interception so model-authored summaries are used.
Module C — Session management
| Tool | Purpose |
|---|
session_list | List sessions (optionally including the trash) |
session_trash | Archive + move a session's artifact into the plugin trash (recoverable; refuses running sessions) |
session_restore | Move it back and unarchive |
session_purge | Permanently delete artifact + trash entry |
Trash entries persist as JSON under $DSH_HOME/dsh-session-handoff-trash/
(keeps the newest 10; oldest overflow auto-purged).
Module D — Model routes (same model, many vendors)
| Tool | Purpose |
|---|
model_routes | List every route serving deepseek-v4-flash: provider, baseURL, key env + family (ark-/sk-), default marker (incl. vision-toolkit- variants), vision wrapper variant |
model_switch | Point agent-default-model at a route (persisted to settings.yaml; new sessions use it). Optional vision:true selects the vision wrapper variant; warns when the key family is missing |
Built for users sharing one model id across official DeepSeek and Volcano
Ark plans: model_routes shows what is configured, model_switch deepseek
uses the Ark lane, model_switch deepseek-official --vision uses the official
lane with the vision wrapper.
Module E — Web client (GUI)
The plugin ships a hand-written client bundle (client/index.js, no build
step) that registers a Settings section "模型路由 / Model Routes" in the
web GUI, mirroring the host tools as clickable controls:
- Model routes panel — every route in the live model directory (the same
list the chat dialog offers, incl. any vision-toolkit wrappers), with the
current chat-context selection shown (
session.requestContext()). No
vision model is configured here — the chat dialog's own model list is the
source of truth; ordering is yours.
- Auto failover (priority list) — drag-to-reorder the routes, delete or
add entries, save the priority. When the active model is unreachable or
out of quota (
QUOTA / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT /
EMPTY_RESPONSE / AUTH / credential / adapter errors), the next route is
tried automatically and work continues — user interruptions never switch.
Backed by GET|POST /dsh-session-handoff/failover and the
agent/request-error + agent/request waterfalls.
- Session handoff — export the current session into
<workspace>/.dsh-handoff/handoff-<session>.md with one button
(POST /dsh-session-handoff/export).
- Compaction thresholds — soft/hard limit sliders (17-90%) persisted into
settings.yaml's
session-handoff: section (GET/POST /dsh-session-handoff/acp).
A "固定推荐 65/90 / Fixed 65/90" button fills the sane default for the
1M-window model directly (no per-session computation in the GUI; the
acp_recommend tool still offers the cost-model estimate for agent use).
Host routes share the exact same logic as the tools (enumerateRoutes,
switchProvider, readAcpSection/writeAcpConfig, exportHandoffForAgent), so the
GUI and the agent tools can never drift.
Soft enhancers (detected, never required)
- OpenViking: when
viking_* tools are present, handoff_export embeds
a ready viking_remember command in the handoff package.
- archify: when
@tt-a1i/archify-dsh is installed, the handoff package
includes an archify render command for a progress diagram.
Core works with neither installed.
Install
dsh plugin --profile web add github:snow-The/dsh-session-handoff
# restart dsh web
Usage
In the old session:
handoff_export → writes .dsh-handoff/handoff-<session>.md (+ handoff package)
In the new session:
handoff_resume → loads the handoff; continue the work
Before heavy work in long sessions:
acp_status → check pressure
acp_compress {start} {end} {summary} → prune spent ranges
acp_set_limit → tune soft/hard limits proactively
Switching vendors for the shared model:
model_routes → see the routes
model_switch deepseek → use the Ark lane
model_switch deepseek-official → use the official lane
model_switch deepseek --vision → ...with the vision wrapper
Development
# unit tests (run from a profile dir so @deepseek-ai/* resolves)
node --test test/
License
MIT
