Session Presentation protocol v2: an additive API for showing more than one Session at once (client-side, backward compatible)

[wanyexin1998]

Motivation

Right now the render layer treats "the current Session" as a single slot: one Session is mounted, everything else is torn down or hidden when you switch. That's the right default for most usage, but it also means a whole category of workflows — comparing two conversations side by side, keeping a reference session open while working in another — can't be built as a plugin on stock DeepSeek Harness Web. The gap isn't a missing setting; it's that the pieces a plugin would need (a second mount point, a way to say "these two Sessions are both visible," the Conversation internals) aren't exposed on the client surface today. Any plugin trying to do this ends up forking internals rather than composing with the public API.

@weijiafu14 went and enumerated the web shell's SlotMap declarations from a real 0.1.1-rc.2 install — 43 seats — and found that the single-session constraint is enforced twice over: conversation is a single seat, and the conversation.view ring, though itself a list seat, renders its session bodies one at a time via only: <active id>. That evidence also sharpens the gap this proposal is closing: a second conversation's data can already be shown today — for example, a custom shell.overlay panel with its own renderer and its own polled data — but a second Session cannot be mounted: reusing the host Conversation renderer, getting session-scoped seats, taking host input, and showing up in lineage are all unavailable to a plugin, and mounting a second Session is exactly what this API is about.

I've been running a fork with a small additive API that closes this gap, and wanted to bring the design here before going further with it, given external PRs are closed right now.

Proposed API sketch

A new face on SessionRuntime, versioned so it can evolve independently of everything else:

interface SessionsPresentation {
  readonly protocol: 2;

  // observable state
  readonly state: Readable<{
    visible: SessionId[];
    focused?: SessionId;
    capacity: number;
  }>;

  // actions
  open(id: SessionId): void;
  focus(id: SessionId): void;
  close(id: SessionId): void;

  // effect-lifetime capacity request, max-wins arbitration
  requestCapacity(n: number): () => void;
}

// surfaced as: sessionRuntime.sessions.presentation

Behavior contract

• visible owns pane membership — left-to-right order is stable and only changes on explicit open/close, never as a side effect of focus.
• focused owns interaction routing only — changing focus never mounts, unmounts, or reorders panes.
• A plain click on a session replaces the focused pane (today's behavior, unchanged for capacity: 1).
• Ctrl/Cmd-click opens a session beside the current one (subject to capacity).
• Closing a pane removes it from visible; the underlying Session is untouched and remains addressable — closing a pane is not deleting a session.
• requestCapacity(n) is effect-scoped (returns a disposer) with max-wins arbitration across concurrent requesters, so plugins don't have to coordinate with each other directly.
• Default capacity is 1, which reproduces existing single-session behavior exactly. A plugin that doesn't know about presentation sees no change at all — fail-closed by construction.

Session-scoped slots when capacity > 1

• Session-scoped seat registrations are instantiated once per visible session, each under its own explicit SessionProvider(sessionId) subtree.
• focused governs interaction routing only; it is never the instantiation gate.
• At capacity: 1 (default) there is exactly one provider subtree — identical to current behavior.
• This API does not retroactively guarantee existing session-scoped plugins are safe above capacity 1; plugins that key state globally rather than by session id should audit before opting in.

Reference implementation

There's a working implementation on my fork, offered here for review/cherry-picking — not as a PR (I know external PRs are closed), just so the shape is concrete rather than hypothetical, and I'm equally happy for it to be discarded if the team goes a different direction:

• Fork: github.com/wanyexin1998/deepseek-harness, branch codex/presentation-v2
• Base: upstream b150a551b8d465e31e418e1b2eaf5e79bbb7d28e (release 0.1.1-rc.2)
• Head: 53015a6f39710dac52ed08f05aca0c6bad7444ac
• Size: 3 commits, ~81 files, +1671/−171. Of that, roughly 500–600 lines are production code across four client packages (client/runtime — contract, service, and the presentation state machine; ui-layout — a two-column AppFrame grid with split-ratio persistence, clamped 0.30–0.70; ui-renderer — session provider; ui-slots — renderer wiring). The remainder is unit tests, e2e snapshot tests, and architecture notes.
• Worth noting: the stock 0.1.1-rc.2 client/runtime/sessions/service.d.ts already says the staged state "can widen to a multi-pane list later" — so this may already be roughly where the team is headed, and I'd rather converge with that than duplicate it.

A real-world consumer

I maintain DSH Workbench, a plugin that adds a two-pane split view (per-pane Navigator, shortcuts, a same-workspace warning, 187 tests) on top of this API. It's been a useful forcing function for the design — the contract above is shaped by actually building something against it, not written in the abstract.

Open questions for the team

• Is "protocol 2" the right number/name at all? I picked it unilaterally on the fork purely as a version tag for my own iteration — happy to renumber, rename, or reshape the surface entirely to match whatever convention you'd use internally.
• Does this collide with an existing internal multi-pane design? If there's already a direction in progress, I'd much rather adapt DSH Workbench to that than have two competing shapes.
• Any concerns with the visible/focused split, or the requestCapacity arbitration model, from a client-runtime design standpoint?

Happy to answer questions, share more of the diff, or just leave this here for whenever it's useful. Thanks for reading this far, and for keeping Discussions open for this kind of thing.

---

中文摘要 (TL;DR)

提案:在 SessionRuntime 上新增一个小型、可独立演进的 sessions.presentation 接口(protocol: 2),让插件可以同时呈现多个 Session,而不是只有"当前 Session"这一个槽位。

为什么插件做不到:现有渲染层一次只挂载一个 Session,且 Conversation 相关内部组件未导出,所以"两个会话并排显示"这类需求无法在不改动客户端内核的前提下以插件形式实现。

接口设计要点:

• 状态 { visible, focused?, capacity }:visible 决定面板的稳定从左到右排列;focused 只负责交互路由(哪个面板接收输入),切换焦点不会挂载/卸载/重排任何面板。
• 动作 open / focus / close;requestCapacity(n) 是绑定到调用方生命周期的容量请求,多个请求方之间按"取最大值"仲裁。
• 默认 capacity 为 1,与现状完全一致;未适配的插件行为不变(fail-closed,向后兼容)。
• capacity > 1 时,session 级插槽按每个可见 Session 各实例化一份(各自绑定独立的 SessionProvider(sessionId));focused 只负责交互路由,从不决定实例化;capacity: 1 时与现状完全一致;但不保证未按 session id 键控状态的现有插件在双实例并存时仍然安全。

参考实现:已在个人 fork(github.com/wanyexin1998/deepseek-harness,分支 codex/presentation-v2,基于上游 0.1.1-rc.2)完整实现并测试,约 500–600 行生产代码分布在四个 client 包中,其余为单元测试、e2e 快照测试与架构文档。提供出来仅供官方参考或摘取,并非 PR 请求——完全理解目前不接受外部 PR,官方也完全可以采纳、改造或直接不用。

真实消费者:DSH Workbench 插件(双栏分屏、独立 Navigator、快捷键、同工作区提醒,187 个测试)目前基于此 fork 运行。

想请教官方的问题:"protocol 2" 这个编号是我单方面定的,愿意按官方习惯重新命名/编号/调整接口形状;这个方向是否与官方内部已有的多面板规划冲突;visible/focused 的划分和 requestCapacity 的仲裁方式是否合理。

Edited 2026-08-27: folded in the 43-seat slot inventory evidence and the showing-vs-mounting framing from @weijiafu14's comment below, and added the "Session-scoped slots when capacity > 1" contract subsection.

[weijiafu14]

Your premise checks out against the host's own slot declarations, and I can add first-hand evidence on both halves — because I built the workaround, and its limitations are exactly the argument for this API.

1. The single-slot property is declared twice, not just a default.

I enumerated the web shell's SlotMap declarations out of a real install tree (@deepseek-ai/dsh-client-ui-{layout,conversation,settings,input-trigger} and -sidebar, 0.1.1-rc.2) — 43 seats. Relevant rows:

seat	kind	scope
conversation	single	session-maybe
conversation.view	list	session
conversation.session	single	session
shell.overlay	list	root

conversation.view being a list looks like an opening, but the official comment closes it: the view ring holds one list entry per view tab (chat here; trajectory/waterfall from ui-trajectory), and the session body renders one at a time by only: <active id>. So "one Session mounted" is enforced both by conversation being a single seat and by the view ring's one-at-a-time render. Worth quoting in your proposal — it makes "this is not a missing setting" concrete.

2. What an out-of-tree plugin CAN do today, and what it costs.

My plugin ships a floating side-conversation panel. It occupies shell.overlay — the only additive frame seat — portaled to <body>, and it shows a second conversation next to the main one. So "display a second conversation" is already possible, and I would expect a reviewer to say so. Which is why the distinction your proposal turns on needs to be stated loudly:

• it is our panel, rendering our data, fetched over our own HTTP route (we poll it; there is no push channel for an out-of-tree client half);
• it cannot reuse the host's Conversation renderer, so it does not look or behave like a session pane;
• it is not a mounted Session — no host input routing, no lineage UI, no trajectory view, no session-scoped seats rendering into it.

So: showing a second conversation is possible today and is not what is missing. Mounting a second Session is what is missing, and it is missing because the Conversation internals are not on the client surface. Framing it that way pre-empts the "just use shell.overlay" response.

3. One backward-compatibility consequence I think your section under-states.

Every session-scoped seat currently renders for exactly one live session. With capacity > 1, conversation.input.dock, conversation.session.header.utilities, conversation.chat.* and friends render twice, concurrently, for two different sessions. My own client half keys all of its state by session id, so it might survive that — but I cannot claim it does, because two visible sessions are not constructible today, so nobody's plugin has ever been exercised in that state.

That is not an objection; capacity: 1 by default genuinely preserves today's behavior. It is a request that the proposal say explicitly what a session-scoped slot registration is promised when two sessions are visible — is each registration instantiated per visible session, is focused the one that gets it, is it up to the plugin to read a session id from scope? Every existing client plugin has an implicit assumption there, and whichever answer you pick will be right for some of them and wrong for others. Naming it in the contract is much cheaper than discovering it after the fact.

Interest disclosure: I maintain a third-party DSH plugin with a browser half, which is where the seat inventory and the overlay experience come from. The client runtime is DSH's own — we do not modify it and could not implement this; I am a consumer of the API you are proposing, not a competitor to it.

[wanyexin1998]

Thanks for the pushback — this is a stronger version of the proposal than what I posted, and it's more useful to fix it here than after the fact.

1. The seat inventory. Good catch, and thanks for actually going and counting instead of taking my word for it. conversation being a single seat and the view ring rendering "one at a time by only: <active id>" is a cleaner argument than the vague "the render layer treats it as a single slot" I wrote. I'll fold your inventory into the Motivation section, credited to you, instead of my hand-wavier version.

2. Showing vs. mounting. Agreed, and it's the right pre-emption before someone posts "just use shell.overlay." Your panel proves a second conversation's data can be shown today; what it can't do — reuse the host Conversation renderer, get session-scoped seats, take host input, show up in lineage — is exactly what "mounting a second Session" means. I'll adopt that framing in Motivation.

3. The dual-instance gap. This is the one you're right to press hardest on — it was genuinely underspecified. The fork's actual answer: each visible session gets its own SessionProvider(sessionId) subtree (two-column AppFrame), so session-scoped seats are instantiated once per visible session, and a plugin reads its session id from that provider's scope — not from focused, which only routes interaction (shortcuts, command routing, highlighting) and never mounts, unmounts, or reorders anything. At capacity: 1 there's exactly one subtree, unchanged from today.

But you're also right that "per-visible-session" is the fork's design choice, not a law of nature — no third-party plugin has ever actually run with two live subtrees, and one that keeps state keyed globally instead of by session id can misbehave at capacity 2. That belongs in the contract, not discovered later:

Session-scoped slots when capacity > 1

• Session-scoped seat registrations are instantiated once per visible session, each under its own session-scoped provider.
• focused governs interaction routing only; it is never the instantiation gate.
• At capacity: 1 (default), there is exactly one provider subtree — identical to current behavior.
• This API does not retroactively guarantee existing session-scoped plugins are safe above capacity 1; plugins that key state globally rather than by session id should audit before opting in.

Since you maintain a plugin that owns real session-scoped seats, I'd genuinely value your read on whether that wording is auditable against your actual implementation, or whether it's still missing the specific hook you'd need to check it against.

[denial123789]

I checked the proposal against the rc.2 runtime/renderer boundary. The visible/focused split is the right starting invariant, but I think four semantics need to be part of the protocol rather than left to consumers.

1. Named render binding. Today SessionProvider reads one Host sessions.provideInfo observable tied to current selection. A pane needs a stable bundle for its explicit id (provideInfo(id) or <SessionProvider sessionId={id}>). If it reads global focus/current, a focus change can retarget data under the wrong component identity.
2. Capacity shrink. Max-wins effect holders work for admission, but releasing a holder can make capacity < visible.length. Capacity must not become implicit eviction authority. Keep existing membership and refuse new opens, or require an explicit user-visible reconciliation operation.
3. Async interaction identity. Send, paste, upload, model selection, question, and approval actions must capture the pane Session id at initiation. Resolving the target from global focus after an await can send a completion to the other pane.
4. Session-scoped multiplicity. I agree with the earlier comment: either every visible pane instantiates Session-scoped slots, or the protocol must classify focus-only seats separately. Existing plugins need an opt-in/compatibility signal before they are rendered concurrently. A safe initial contract also forbids duplicate ids in visible.

For transition completeness, I would also make “open while full” return a typed capacity result rather than silently replace; close must never archive/delete/cancel; closing the focused pane needs one pinned neighbor rule; and external Session removal should be a separate reconciliation event.

On naming, protocol: 2 currently reads like the second version of a public contract, while rc.2 has no presentation protocol 1. I would start at 1 or use a capability/version pair whose number is independent of the implementation fork. Unknown versions should fail closed to capacity one.

I wrote out the verified rc.2 boundary, transition table, capacity-holder rules, per-id provider shape, persistence validation, failure router, and 22 acceptance cases here: https://sandbaseai.github.io/deepseek-harness-handbook/multi-session-presentation-contract.html

Disclosure: I maintain this independent SandBase handbook; the API recommendations are design analysis, not shipped DSH behavior.

[wanyexin1998]

This is exactly the kind of boundary-level review the proposal needed.

1. Named render binding. Agreed, and the fork already does this: every visible session mounts under its own SessionProvider(sessionId) with a per-id provide bundle — nothing reads global focus/current to source pane data. The proposal text treated this as an implementation detail rather than a protocol requirement, which is a gap in the writeup, not the design. Promoting it to a normative clause.

2. Capacity shrink. Genuine tradeoff, not settled. Current fork behavior: releasing the last capacity-2 holder collapses presentation around the focused session. Rationale: a capacity holder releasing usually means the feature that opened the second pane (e.g. a split-pane plugin) is unloading, and admission-only capacity would leave a pane standing that nothing loaded supports anymore. But "implicit eviction authority" is a fair characterization — the durable Session is untouched, yet membership shrinks without a user gesture. Two honest paths: specify collapse as an explicit, deterministic reconciliation operation instead of a silent side effect, or go admission-only and refuse new opens instead of evicting. This isn't my call alone — interested in your read, and upstream's, on which.

3. Async interaction identity. Agreed this must be normative. The pane-scoped provider structure is designed for exactly this — bind session id at initiation, not from global focus after an await — but I won't claim every send/paste/upload/model-selection/question/approval path has been audited against that rule. I'll audit the fork against it. Regardless of the outcome, this belongs in the contract plus a dedicated acceptance case.

4. Session-scoped multiplicity.

• Duplicate ids in visible: forbidden, adopting verbatim.
• Close-never-archives, pinned-neighbor-on-focused-close, external-removal-as-separate-reconciliation-event: the fork/Workbench contract already specifies close retains the durable Session and focuses right-then-left neighbor. These were implicit; making them normative text in the proposal instead of assumed.
• Opt-in/compatibility signal: real improvement over the audit-caveat wording just added. Open to your focus-only classification as the backward-compat default — unadapted session-scoped seats render only under the focused pane, a capability flag unlocks per-visible-pane instantiation. Worth pinning down together, not deciding unilaterally here.

5. Open-while-full. Splitting it: open() returns a typed outcome (opened | replaced-focused | refused) so callers see the capacity decision instead of inferring it. Default UI gesture still maps to replace-focused — continuous with the "click replaces the view" behavior users already expect. API semantics explicit, gesture semantics unchanged.

6. Versioning. Conceded outright — protocol: 2 was fork-side numbering and reads wrong for a public contract with no protocol 1. Start at 1, or move to a capability/version pair whose numbering upstream owns. Unknown versions fail closed to capacity one. Same lesson applies consumer-side: the Workbench plugin's version guard is being tightened from a bare protocol-number equality check to structural probing, for the same collision risk your naming critique points at.

7. Handbook. Thanks for the transition table and the 22 acceptance cases. Plan is to run them against the fork's e2e snapshots and report which pass and which don't — not endorsing sight-unseen ahead of that.

Let me know which of the open calls — capacity-shrink semantics or the opt-in signal shape — you'd want pinned down first.

[TommyZeng777]

I would like to add a real-world plugin case based on dsh-v0.1.2-alpha.2.
Discussion #2346 has been marked as resolved and closed. However, neither the current Alpha.2 release nor the current GitHub master exposes openSession(sessionId, viewId), selectView, or an equivalent public API on IConversation.
To open a Session and then switch to a specific Chat or Learning view, REDMath still has to:

• query [role="tab"] elements;
• invoke DOM .click();
• use MutationObserver to wait for the target surface to mount;
• implement latest-wins behavior, cancellation, timeouts, and failure cleanup independently.
  This workaround has already caused several real regressions:
• the Session changed, but the active view did not;
• navigation reported success even though the visible surface remained unchanged;
• the native New Session or Conversation page briefly flashed;
• the same tab was clicked repeatedly by competing navigation paths.
  Could the maintainers clarify which replacement API or design made Proposal: public cross-session conversation view navigation for Web plugins #2346 resolved?
  If no equivalent public API currently exists, I hope the presentation contract discussed in Session Presentation protocol v2: an additive API for showing more than one Session at once (client-side, backward compatible) #4718 can also include an atomic operation such as:
  navigate(sessionId, viewId)
  // or
  open(sessionId, viewId)
  This operation should own Session activation and target-view selection as one cancellable, latest-wins transaction, rather than covering only multi-Session visible and focused state.