dsh-session-handoff

English | 中文

Hand your long DSH session over to a clean one. /handoff summarizes the recent conversation with an LLM, creates a brand-new session + agent in the same workspace (no history copied), injects a structured handoff document as its first message, and auto-opens it — the model continues from the summary instead of replaying the whole old history. The origin session is untouched.

Features

• One command — /handoff [<N>|all] (defaults to the last 8 user messages; all covers everything)
• Clean handoff — a fresh session with the origin's workspace, model route, and agent preset (system prompt / tools / skills), no context bloat
• Structured summary — 任务目标 / 当前进度 / 关键决策 / 涉及文件 / 下一步 / 遗留问题
• Auto-open — the client half waits for the new session to be ready and navigates to it (each child auto-opens once; history replay never re-jumps)
• Robust by default — summaries run with thinking off (fast, cheap), oversized excerpts keep the newest messages instead of erroring, and finish reasons (max-tokens / error / aborted) are translated into actionable errors
• Zero core changes — a single dsh.bundle.patch row; only public services are used

Install

# 1. Build the bundle from source (or grab a release tarball)
npm install && npm run build && npm pack     # → dsh-session-handoff-0.2.0.tgz

# 2. Install into your web profile
dsh plugin --profile web add ./dsh-session-handoff-0.2.0.tgz

# 3. Restart and verify the row is mounted
dsh web
dsh --profile web --dump-config | grep handoff
# expected: # == dsh-session-handoff / - id: handoff / - name: dsh-session-handoff

Dev-time source link (dsh plugin --profile web add D:/path/to/dsh-session-handoff) requires the source dir's node_modules to resolve @deepseek-ai/* peers; prefer the tarball.

Usage

Type in any conversation's input box:

/handoff          # summarize the last 8 user messages (default)
/handoff 20       # summarize the last 20 (same as turns=20)
/handoff all      # summarize every user message (same as turns=all)

What happens:

1. A command card shows "summarizing…";
2. An LLM produces the handoff document (goal / progress / decisions / files / next steps / open questions), which becomes the new session's first message;
3. The new session auto-opens; the origin session stays intact and is linked back.

⚠️ Privacy: the recent conversation text (user + assistant messages in the requested window) is sent to the configured model to produce the summary.

Configuration

- id: handoff
  name: dsh-session-handoff
  config:
    turns: 8            # user-message rounds to extract (1–50)
    maxInputChars: 24000  # byte cap for the summary input (oldest dropped first)
    maxTokens: 2000     # summary output budget
    reasoningEffort: off  # off (default, fast/cheap) | high | max | inherit
    timeoutMs: 120000   # summary call timeout
    # provider: deepseek-official   # optional fixed model route
    # model: deepseek-v4-flash      # must be paired with provider

Without provider/model, the current session's latest logged model route (session.requestHeader()) is used.

How it works

• Host half (index.mjs, plain ESM): public services only — commands (/handoff), llm (ctx.llm.stream, following official session-title-llm), agents (ctx.agents.create — session and agent together, inheriting the origin's cwd / model route / agent preset via agentPresets.mount), plus workspaceRegistry.attachSession (same-workspace grouping) and sessionTitle.rename (a handoff: <source> title).
• Client half (src/client/, tsdown → lib/client.js): a handoff conversation node matches the /handoff success event and auto-opens the child session (polling until it is addressable, deduped via localStorage).

Development

npm install        # devDeps: tsdown / typescript / @types/react / vitest / jsdom ...
npm test           # 19 tests: 15 host+client pure functions + 4 client component
npm run typecheck
npm run build      # tsdown → lib/client.js (CJS factory, official client-module format)
npm pack           # prepack runs typecheck + build automatically

Publish checklist: add the dsh-plugin GitHub topic → open a PR to awesome-deepseek-harness → optionally npm publish.

Known limitations

• The handoff document lives in the session only; it is not written to disk (HANDOFF.md is a future enhancement).
• Targets the rc.5 public contracts; re-check on DSH upgrades.
• The auto-open component has pure-function tests only; jsdom component tests are pending.

License

MIT