dsh-session-buddy

dsh-session-buddy

English | 中文

Session notifications + an in-conversation ladder outline for the DeepSeek Harness Web GUI (dsh web). Get notified when the AI finishes replying, asks you a question, or needs command approval — even while the tab is away — and navigate past questions via a compact outline rail.

_{Built independently with dsh + Deepseek-V4-Flash}

Features

Session notifications

• Three trigger kinds, each independently switchable:
  • reply: the AI finished replying
  • ask: the AI explicitly asks you a question (ask-user tool) — a plain finished reply does NOT re-fire
  • confirm: a command approval is pending (approval dialog)
• A reply notifies when you were away at any point during that turn; stays silent while you watch it
• Host-driven + cross-tab: triggers come from the session event log (reply on a completed turn, ask on the ask-user tool, confirm on an approval request) relayed over SSE to every open tab, and each event pops at most one OS toast — a notified ledger claims it once across tabs and reloads; DOM observation is the fallback while the stream is down
• Native OS toast (Windows PowerShell WinRT / macOS osascript / Linux notify-send) — no browser permission, not suppressed by Chrome — plus a red-dot favicon & (●) title badge, and an optional sound
• Title is "workspace · session title"; one notification per reply

Ladder outline

• A collapsible rail on the right side listing every user question in order
• Thin rounded bars when idle (no text, no crowding), even with dozens/hundreds of turns
• Hover a rung for a floating tooltip (number + question summary + time); click to scroll to that turn with a flash highlight
• Scrollspy highlights the current turn; a jump-to-latest button appears when you are not at the bottom
• Older history is paged in on demand via the "+older" footer
• Hidden automatically when the session has fewer than two turns
• The rail anchors to the conversation's right edge and follows it whenever a sidebar expands/shrinks the conversation (event-driven, zero idle cost)

In-app upgrades

• The settings card shows the current version and can check the npm registry for the latest release
• One-click upgrade through the official dsh plugin add CLI (restart dsh web to apply)

Session cleanup

• Corrupt sessions — whose history fails the harness's own load validation (e.g. a tool/result persisted with an empty tool call id, which dsh refuses to read back) — are marked with a small warning badge on the session row
• The session row's three-dot menu gains a "删除会话" item: confirm, and the session's data is permanently deleted from disk (frees space) — dsh itself only offers fork/archive (archive keeps the files)
• Deleting is hidden for the currently open session, and the host refuses to delete a live session

Tool-run collapsing

• After each turn finishes, the tool calls that turn executed (Pwsh / Think / Write / Grep / Edit / Read …) are folded into a single "共执行 X 步操作" row, so the closing summary is directly visible
• Click the row to expand the individual tool cards again (state is remembered per session)
• A turn is only folded once it has actually ended (a running turn stays fully visible); switch it off in the settings card to always show every tool call

Transcript folding

• Fold think blocks + process notes — after a turn finishes, its repeated Think reasoning blocks, the interleaved text "小结" notes, and any context injections between them merge into one "共 N 次思考" row (the turn's final summary stays visible); click to expand them again
• Fold over-long questions — a question whose text runs past 6 lines (e.g. a whole log pasted into the prompt) is clamped to those first lines with a soft bottom fade and an "展开全文" bar; click to expand the full text
• Each folding surface has its own switch in the settings card (折叠工具操作 / 折叠思考块 / 折叠长提问), and expand/collapse state is remembered per session

Install

From npm

dsh plugin --profile web add dsh-session-buddy

From a local directory (development)

dsh plugin --profile web add link:<this-dir>

After installing, restart dsh web, then configure it under 设置 → 插件 → 插件配置 → "Session Buddy @Shrbuz".

Upgrade

Two ways to upgrade to a newer version:

CLI

dsh plugin --profile web update dsh-session-buddy

The plugin is installed as a semver range (^0.x.y), so dsh plugin update picks up the newest compatible release. To force a specific version:

dsh plugin --profile web add dsh-session-buddy@<version>

In-app

Open the plugin settings card → "Version & upgrades" → "Check for updates", then click "Upgrade" when a newer version exists.

After upgrading either way, restart dsh web to load the new version.

Usage

Notifications

• Open the plugin settings card and toggle the three trigger kinds, the sound, and the master switch
• Switch away from the tab while the AI is replying and you will get a native toast when it finishes; if the AI asks you a question or needs an approval, you are notified while the tab is hidden

Ladder outline

• Hover the right-side rail to preview each question; click a rung to jump to it
• Use the +older footer to page in hidden history; the jump-to-latest button scrolls to the bottom
• Rung length and tooltip timestamps are configurable in the settings card
• When many rungs exceed the rail height, the scrollbar is hidden and top/bottom fade shadows indicate there is more above/below; the +older footer stays fixed and always reachable

Upgrades

• See the Upgrade section above — via dsh plugin update or the settings card ("Version & upgrades")

How it works

Layer	Implementation
Notifications	Host watches the session event log and relays reply/ask/confirm triggers over SSE (/api/session-buddy/events) to every tab; a notified ledger claimed at the loopback-only /api/session-buddy/toast route dedupes across tabs and reloads (one OS toast per event). Client-side DOM observation (MutationObserver + official anchors + the composer stop-button running signal) is the fallback while the stream is down
Outline	Rungs come from the official sessions service snapshot (independent of how much DOM is rendered); dsh conversation history is a paged window, so the outline pages hidden history in on demand and aligns rungs to the DOM via the official anchor keys
Upgrades	The host reads https://registry.npmjs.org/dsh-session-buddy/latest (fail-closed when offline) and runs the official dsh plugin CLI for the actual upgrade
Session cleanup	The host lists sessions via sessionPersistence, flags corruption by replicating the harness's own load-time message validation, and deletes a session's directory (resolved through the persistence service's locate(), never from user input); the browser marks corrupt rows and injects the delete item into the row menu
Tool-run collapsing	Pure client DOM pass over the official anchor rows: tool-call rows are grouped by their enclosing turn-tail row (the tail is only published after turn/end, so folding happens exactly when the turn is finished), each group collapses to a "共执行 X 步操作" chip with per-session expand state
Transcript folding	The same official-markers pass groups a turn's assistant-step rows (think blocks + text "小结" + context injections) by its turn-tail row into a "共 N 次思考" chip, leaving the final summary visible; over-long user rows are clamped to 6 lines with an expand bar. Both silently degrade if the official markers vanish
Outline positioning	The rail re-reads the conversation scrollport's right edge on resize, on container/ancestor resize, and on DOM mutations (coalesced to one pass per frame), so it always moves with the conversation width

The UI is theme-aware and styled entirely with the official --dsw-alias-* design tokens.

Limitations

• Native toasts depend on the OS notification settings; the favicon/title badge always works as a parallel cue
• The "one OS toast per event" dedup applies to the host-driven stream; while that stream is down (older host, or a connection failure) the DOM fallback notifies per tab, so several hidden tabs could each pop a toast for the same event
• Session deletion is permanent (no recycle bin); the "删除会话" item is only injected into the session menu while the menu DOM is recognizable, and degrades silently otherwise
• All folding surfaces rely on the official data-chat-flow-kind / data-chat-anchor-key markers (question clamping additionally on the _text_ class); if a future dsh version drops them, the plugin silently stops folding (it never hides rows it cannot confidently attribute to a finished turn)
• An upgrade takes effect only after restarting dsh web

Development

pnpm install
pnpm build          # tsc -b && tsdown → lib/
pnpm typecheck

Regression scripts:

node scripts/smoke-host.mjs        # host-logic smoke (no web)
node scripts/verify-live.mjs       # live check against a running dsh (boot graph + bundle + routes)
node scripts/verify-outline.mjs    # CDP: restore session, page hidden history, rung click/flash
node scripts/verify-tooltip.mjs    # CDP: hover tooltip on a paged-in rung
node scripts/verify-notify.mjs     # CDP: notification fires while hidden, silent while visible

License

Apache-2.0