dsh-session-handoff

@snow-the/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:

1. Handoff — export a structured, portable handoff document so a fresh
   session can continue seamlessly.
2. Active context pruning — compress spent history before the context
   window fills (official compaction API, model-authored summaries).
3. Session management — trash / restore / purge / list sessions.
4. 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.
5. 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