[Proposal] Plugin extension points for global navigation and global pages

[LH-kevin]

Summary

Plugins today can register many additive surfaces inside a session (header rows, composer chrome, message actions, per-session views) and one frame-wide shell.overlay.

There is currently no supported contract for a workspace-independent global navigation entry plus a global page.

A plugin that needs its own top-level destination — for example a task manager, search surface, reports page, or other workspace-independent view — has no natural place in the Harness shell.

This is a capability request for the generic extension model, not a request for any single plugin. It comes from building a real third-party plugin and finding no supported surface for this class of UI.

Problem

The sidebar column (SidebarRoot) is currently composed approximately as:

brand (+ toggle)
New Session
sidebar.workspaces
footer:
  sidebar.footer.action
  sidebar.settings

There is no additive seat between New Session and the workspace region.

The existing additive sidebar surfaces are primarily:

• sidebar.brand.mark
• sidebar.brand.name
• sidebar.footer.action

sidebar.footer.action renders below the workspace region, so it does not represent a primary global-navigation location.

Separately, top-level selection is currently centered around SessionListState.current: SessionId | undefined, together with session-scoped conversation.view entries.

There is no root-scoped third-party global page/view registry.

As a result, a destination that is neither a Conversation nor a Workspace cannot be represented through the current supported plugin contracts.

Source evidence

Relevant areas in the current source:

• packages/client/ui-sidebar/src/client/SidebarRoot.tsx

  • renders the brand row
  • renders the hard-coded New Session action
  • then renders sidebar.workspaces
  • then the footer slots

• packages/client/ui-sidebar/src/client/contract/slots.ts

  • sidebar.workspaces is a root-scoped single slot
  • sidebar.footer.action is a root-scoped list slot
  • there is no additive slot between New Session and the workspace region

• packages/client/runtime/src/client/sessions/service.ts

• packages/client/runtime/src/client/sessions/manager.ts

  • top-level selection is session-oriented

• packages/client/ui-conversation/src/client/contract/slots.ts

  • conversation.view is session-scoped rather than global

Candidate navigation contract

One small, backward-compatible extension could be a new root-scoped list slot between New Session and sidebar.workspaces, for example:

'sidebar.navigation': {
  kind: 'list',
  scope: 'root',
  owner: SidebarNavigationOwnerProps,
}

The exact name and owner shape are only suggestions.

It could use the existing slot-registration model:

ctx.slots.inject(key, () =>
  ctx.slots.register(
    {
      name,
      id,
      order,
    },
    Component,
  ),
)

This would reuse existing slot behavior for deterministic ordering and automatic cleanup when a plugin unloads.

Useful properties for an entry would include:

• additive registration
• deterministic order
• icon
• label
• active / selected state
• a navigation action or target
• automatic removal on plugin unload
• no need to masquerade as a Workspace or Conversation

Global page design question

The navigation entry is only half of the problem: clicking it needs to open a real global surface.

The Harness does not currently appear to expose a root-scoped global page/view registry.

I would appreciate maintainer guidance on how such a surface should integrate with the existing navigation model.

Questions that seem important:

1. Is a root-scoped global view/page registry the right abstraction?
2. Where should the selected global-page state live?
3. How should it relate to SessionListState.current?
4. When a global page is active, should the current session remain selected but hidden, or should session selection be cleared?
5. Should refresh restore the active global page?
6. Should browser back/forward and URL state participate?
7. What should happen if the owning plugin unloads while its page is active?
8. What should the precedence be between a global page and conversation/workspace views?

An illustrative model might look like:

'app.page': {
  kind: 'list',
  scope: 'root',
  owner: PageOwnerProps,
}

plus some root-level selected-page state.

This is only intended to make the discussion concrete — not as a prescriptive API proposal.

Backward compatibility

Ideally this could be introduced additively:

• do not change existing slot semantics
• do not change sidebar.workspaces
• do not change sidebar.footer.action
• do not change sidebar.settings
• do not change the existing New Session behavior
• render exactly as today when no plugin registers a global navigation entry/page

Example use cases

This capability could support more than one plugin or product feature, for example:

• global scheduled/task management
• workspace-independent search across sessions
• reports / usage / metrics
• plugin-level dashboards
• other extension views that are neither Conversations nor Workspaces

A workspace-independent scheduled-tasks surface is one real example that motivated this investigation, but the requested capability is intentionally generic.

Questions for maintainers

1. Would a root-scoped list slot between New Session and sidebar.workspaces fit the intended extension model?
2. Does a name such as sidebar.navigation fit the project's slot naming conventions?
3. Is there already a plan for root/global plugin views that I may have missed?
4. If a global-page registry is desirable, should its selected-state ownership belong to the sessions service, layout service, or a separate navigation service?
5. Would you prefer the navigation slot to be proposed independently first, with global-page semantics discussed separately?

I couldn't find an existing public discussion, issue, or PR covering this. If this is already being discussed elsewhere or internally, please point me to the relevant direction.

[LH-kevin]

Hi @imccyu — sorry for the ping. This proposal is currently blocking a real third-party plugin use case around adding global navigation/page surfaces without replacing shipped UI. Since you've recently worked on the client slot/layout architecture, I'd appreciate any guidance on whether this direction fits the intended extension model. Thanks!

[zweix123]

Concrete case: returning from a plugin page to native conversation UI

We are building a workflow plugin that uses the public conversation slot to display a workflow page in the main content area.

Opening and disposing the custom page already works. The missing part is reliably returning to the native conversation UI when the user clicks an existing Session or New Session in the native sidebar.

On 0.1.2-rc.1, we could not find a public API that exposes this navigation intent. Watching Session state is insufficient in at least two cases:

• the user clicks the currently selected Session again;
• the user clicks New Session repeatedly when no Workspace is available.

These actions may leave the observable Session state unchanged. General Session-list notifications are also unsuitable because they include background data updates that are unrelated to user navigation.

Our current fallback is to listen for clicks on specific native DOM elements and dispose our conversation slot registration. This works, but it couples the plugin to the host's DOM structure and creates ongoing compatibility work whenever the native UI changes.

Would it be possible to expose a public navigation event or service that lets plugins observe native actions such as:

• open a Session;
• create or enter a new Session;
• reselect the current Session;

including cases where the navigation target or Session state does not change?

We do not have a strong preference between an event-based API and a navigation service and would be happy to follow the project's architectural direction. The key requirement is to distinguish user navigation intent from background Session data updates.

If a supported mechanism already exists, a complete example covering entry into a custom main page, exit through native navigation, and cleanup when the plugin unloads would be very helpful.

We can provide a minimal reproduction plugin and concrete acceptance cases if useful.

[zweix123]

Related discussion map and a possible convergence point

To avoid losing earlier community work, we searched the titles and bodies of all 5,767 Discussions currently available in this repository (58 pages, including 167 closed Discussions; scan date: 2026-09-07). The following is the set that appears materially related to root-level plugin pages, native navigation, Session/view selection, or the lack of a public action that drives an existing UI slot.

1. Root navigation and plugin-owned pages

• Feature request: additive top-level sidebar navigation for plugins #2873 requests additive top-level sidebar navigation without replacing the sidebar or patching the DOM. Its comments move toward a single shell.page contribution that owns both the navigation entry and page body, including fallback when the contribution is disposed.
• RFC: Runtime-open root page, details, inbox, and plugin-event seams for external UI plugins #3992 proposes runtime-open root pages, details, inbox surfaces, and plugin events through shell.page and ctx.layout.openPage/closePage.
• 提案：为插件提供工作区域与唯一原生会话伴随栏 #4322 proposes a plugin work area while retaining one native Conversation surface as a companion, keeping composer, approvals, attachments, shortcuts, scrolling, and details under one owner.
• [Feature Request] 减少社区插件对第三方插件的强依赖：官方提供一等公民 UI 扩展能力（侧边栏页签/面板），保证安装与更新稳定 #4594 asks for first-class sidebar tabs/panels so plugins do not have to depend on another UI plugin, replace the complete sidebar, or patch the DOM.

These proposals differ in layout, but they share the same underlying need: a plugin needs a supported top-level destination whose selection and lifecycle are coordinated by the host.

2. Session and conversation-view navigation

• Proposal: public cross-session conversation view navigation for Web plugins #2346 proposes public cross-Session conversation-view navigation. It is closed as resolved, but has no comments, accepted answer, or linked upstream implementation, so the replacement API is unclear.
• Expose atomic Session and conversation-view navigation for Web plugins #5192 revisits that request after finding no equivalent API in 0.1.2-alpha.2 or the then-current master. It documents DOM tab clicks, MutationObserver, cancellation, and race handling as the downstream workaround for opening a Session in a specific view.
• New Session draft view keeps the previous session on stage — `current` no longer means what the main column shows (0.1.2-alpha.1) #5035 reports that entering the New Session draft screen can leave list.current pointing at the previous Session. Regardless of the version-specific behavior, it demonstrates why “current Session” and “what the main column is displaying” should not be assumed to be the same state.

These threads mostly cover plugin-initiated navigation. The concrete case added above covers the opposite direction: the user performs native navigation and the plugin page must yield to the native Conversation surface, including when the target Session is unchanged.

3. Multi-Session presentation and renderer ownership

• Proposal: three minimal seams to enable a multi-session split-pane community plugin (with working prototype) #2418 proposes minimal seams for a multi-Session split-pane plugin.
• 多会话 UI 插件的渲染器扩展点（按 id 绑定会话 + 会话列包裹缝） #604 requests by-ID Session rendering and a supported wrapper seam around the native conversation column.
• Session Presentation protocol v2: an additive API for showing more than one Session at once (client-side, backward compatible) #4718 proposes a broader Session Presentation protocol with separate visible and focused state.

These are broader than a single root page, but they reinforce the need to model visible/focused surfaces explicitly instead of deriving presentation solely from the current Session ID.

4. Adjacent examples of “registration exists, control is missing”

• Let client plugins open the conversation details panel (drive the conversation.details.tool slot) #4897 notes that plugins can register conversation.details.tool, but cannot publicly select a tool and open the details panel that would render it.
• 为第三方插件提供宿主→客户端事件转发扩展点（如 session/open） #5358 asks for extensible Host-to-Web event forwarding, using session/open as an example. Its direction is external producer → Web client, so it does not itself provide notification of native Web navigation, but it is relevant to the public event-contract discussion.
• DSH | DSH Codex UI | Codex-style navigation and workspace UI / Codex 风格导航与工作区界面 #4941 demonstrates that a complete alternative navigation/workspace UI can be built downstream. It is useful implementation evidence, but replacing the shell is a substantially larger ownership commitment than registering one host-managed page.

Shared gap

Across these Discussions, the rendering seam and the navigation/control seam are often separated. A plugin may be able to register content, but still cannot reliably:

1. declare that its page is the active main surface;
2. observe that a native Session or New Session action should reactivate the core Conversation surface;
3. detect repeated navigation to the same target, where Session state does not change;
4. distinguish navigation intent from background Session-list updates;
5. rely on host-owned fallback when the active plugin contribution unloads.

That leaves plugins choosing among DOM observation, private stores/components, or replacement of a much larger shell surface.

A possible minimal contract for convergence

The exact API shape can follow the maintainers’ architecture, but a complete contract appears to need these behaviors:

• root-level pages are registered under stable keys and removed with the plugin lifecycle;
• the host owns observable active-surface state, such as “core Conversation” or a registered plugin page;
• a plugin can open and close its page through a public action;
• native Open Session and New Session actions reactivate the core Conversation surface, even when the Session target is already current or otherwise unchanged;
• this navigation signal is separate from Session data/list refresh notifications;
• unloading the active contribution falls back deterministically to a valid core surface.

This could be expressed as a shell.page/layout service, a navigation service, events, or a combination. The important part is that registration, selection, native-navigation exit, and lifecycle fallback form one supported contract.

Based on the scan, no referenced Discussion currently documents a public API covering that complete lifecycle. #4069 therefore looks like a useful place to consolidate the requirement and eventually record the recommended solution. If another thread or implementation already provides it, linking it here would help plugin authors converge on the supported path.