dsh-conversation-rail · session minimap

English | [中文](README.zh.md)

A locator for long conversations in DSH Web. A vertical rail sits along the left edge of the conversation, one bar per turn; hover a bar for a preview card, click it to jump to that turn.

  ▏─────                 ┌──────────────────────────────┐
  ▏───────────           │ Can you patch this without…  │  ← question (one line, dark)
  ▏━━━━━━━━━━━━━━  ◀━━━━━┤ CRLF is already ruled out…   │
  ▏──────                │ only the legal re-encodes…   │  ← answer (up to four lines, dimmed)
  ▏────────              └──────────────────────────────┘

• Bar length = how much text that turn holds (square-root compressed, 10–34px).
• The bold bar = the turn currently at the top of the scroll area.
• The preview card carries prose only: your question plus the assistant's plain

text. Fenced code blocks, tool calls, shell commands, reasoning traces and injected context never reach the card — you cannot skim JSON.

It draws the whole session, not the loaded window

Conversation history is paginated: the front-end snapshot usually holds only the most recent stretch, so an 8-turn session may have 1 turn in the window. The rail is not bound by that:

• The skeleton comes from the host's outline endpoint

(GET /dsh-conversation-rail/api/outline?sessionId=). The host reads the full log with ctx.sessionQuery.readSession(), folds it into a table of contents of roughly a hundred bytes per turn, and returns that — the history itself never crosses the network.

• The live snapshot overrides the part that is loaded: it carries jumpable DOM

anchors, and for a turn that is still streaming it is the only current source. The two are aligned by the user/message event seq, live winning over outline.

• Clicking a bar that isn't loaded yet calls session.loadOlder() repeatedly

until that turn enters the window, then jumps. The bar pulses while paging, with a ceiling of 40 pages — better to not reach a turn than to page through an entire log because of one click.

The outline uses readSession rather than the lighter filterEvents because the latter does not return source. The user/message event type carries both real questions and context injected by agent.inject() (file-change notices, AGENTS.md, skill bodies…); the official docs state all three project content verbatim and are told apart by source. Without that field, injected context would be drawn as turns.

How it attaches

It takes one seat: conversation.session.header.utilities. Not to draw anything in the header — that slot is session-scoped, so the component receives the framework's useSession snapshot hook and sessionId, and its lifetime follows the session. The component renders null in the header; the actual rail is a fixed overlay on body, aligned to the measured rectangle of [data-conversation-scroll]. It stays out of the host layout, so switching skins, collapsing the sidebar or changing the grid cannot squeeze it.

Turn data comes from ConversationSnapshot.chat: walk order, open a turn on a user node, attribute the following assistant-step text blocks to it. Jumping uses the host's own anchors ([data-chat-anchor-key]), the same path its internal scroll positioning takes.

Known boundaries

• The outline is fetched once per session. New turns arrive through the live

snapshot and do not trigger a refetch; only leaving and returning to the session refetches (a 5-second host-side cache absorbs the back-and-forth).

• Jumping to a very early turn loads every page between it and the window.

That is what pagination means: to show turn 1, everything from there up to the loaded window has to come in. Jumping to recent turns pages almost not at all.

• If the outline endpoint fails, the rail degrades to drawing only the loaded

stretch rather than disappearing.

• Previews are rendered as plain text, not markdown: leading #, -, 1. and

emphasis marks are stripped, fenced code is removed entirely.

Install

dsh plugin --profile web add github:dingyi580/dsh-conversation-rail

Then restart dsh web (a newly assembled plugin needs a restart; later code changes can be hot-reloaded with dev_reload_package).

<details> <summary>Installing from a local checkout</summary>

Put the plugin at ~/.dsh/plugins/dsh-conversation-rail, then add two entries to ~/.dsh/profiles/web/package.json:

{
  "dsh": { "profile": { "bundles": ["…", "dsh-conversation-rail"] } },
  "dependencies": {
    "dsh-conversation-rail": "link:/Users/<you>/.dsh/plugins/dsh-conversation-rail"
  }
}

and link it into the profile's node_modules:

ln -sfn ../../../plugins/dsh-conversation-rail ~/.dsh/profiles/web/node_modules/dsh-conversation-rail

</details>

Build

npm run build       # tsc for the host entry + tsdown for src/client → lib/client.js
npm run typecheck   # type check only

lib/ is committed so the plugin installs from GitHub without a build step. Assembly goes through cordis.patch.yml plus the profile's dsh.profile.bundles.

License

BSD-3-Clause