Public native sidebar APIs for persistent sessions, downloads and same-tab tools

[ayushsuletiya]

Initially audited against Harness 0.2.0-rc.2, commit 639ed01; the owning APIs were rechecked at upstream commit 1517a4d on 2026-10-17 and the gaps remain.

Problem

An independently distributed sidebar plugin cannot currently preserve a login across app restarts or manage native downloads using public contracts alone. The desktop creates a process-local random partition, cancels native downloads, and exposes only acquire/release/open-request methods. Same-tab automation also lacks an exported desktop service; an owned plugin UI can use the existing Remote stream API for command/result transport.

The affected workflow is ordinary: install a browser plugin, sign in, download a file, quit, reopen, then ask the model to resume the download in the visible tab. A plugin should not need to edit the installed application archive or replace the application's remote-event assembly to implement this.

Requested supported capabilities

1. Main-process-owned persistent workspace browser sessions, with an explicit user choice and stable session identity. The renderer receives a lease, never direct Electron objects or cookie exports.
2. A versioned public browser service with exact tab IDs, navigation/readiness state and same-tab operations. Header UI and agent tools should use the same service.
3. Main-process-owned downloads: list, pause, resume, cancel, reveal; durable metadata and progress events. Downloads must be scoped to the caller's workspace/session. A resume response should state whether bytes were resumed or the transfer restarted.
4. Document the existing bidirectional Remote stream pattern for plugin-owned browser UI/tool services, with generated strict codecs, peer ownership, cancellation and reconnect examples. A published Gateway source-mode probe passes; no new transport is requested.
5. Header/tab extension contracts for favicons, pinning, ordering and close behavior, so plugins do not need private DOM selectors or stylesheet patches.

Compatibility and migration

• Preserve default behavior until the user opts into a persistent session. Advertise feature/version support explicitly.
• Keep storage under the application's normal platform data directory; do not require an author-specific path.
• Preserve workspace isolation and reject leases owned by another renderer.
• Keep installed plugins/data intact on a compatible app upgrade. Missing capability must produce a clear unavailable feature, not attempt an application patch.
• Do not import cookies, bookmarks, or private files into a published package.

Verification requested upstream

• Mac and Windows: two simultaneously visible tabs with independent leases, cancellation, renderer teardown, plugin unload, and app restart.
• Cookies persist only for opted-in persistent sessions; separate workspaces do not see each other's data.
• Native download completion and interrupted resume verify final file length/hash; changed validators and non-range servers cannot silently corrupt a file.
• Multiple plugin Remote streams coexist and are removed on unload without interrupting unrelated sources.

These capabilities would let independently distributed plugins implement the UI and tool layer without application modifications. This request does not ask to grant arbitrary Electron IPC or remove native authorization.

Existing extension mechanisms and scope

Additive client slots and the Remote stream mechanism already exist; this request does not ask for another transport or a general-purpose Electron escape hatch. Related discussion #9218 covers broader host extension APIs. This request focuses on desktop-owned browser session persistence, downloads and shared tab identity. If a supported route already covers these exact capabilities, documentation of that route would resolve the corresponding part of the request.

Source pointers at the audited commit: browser guests, browser bridge types, and sidebar client.

[nguyenngothuong]

补充一个具体的桌面用户场景，支持这个提议。我的诉求是：网页就在 DSH 官方桌面 app 的现有 Browser tab 中；我手动登录一次，完全退出并重开 app 后仍能继续使用；后续 Agent 操作的也是我看到的同一个 tab。 我希望通过安装插件获得增强，不需要修改安装包、重签名、自建桌面壳，或另外打开 Chrome 才能使用。

当前缺口：不是“能否复用外部 Chrome 登录态”

环境是 macOS、DSH Desktop 0.2.1-rc.1。这里先报告源码/文档检查结果，不把它说成已经完成个人账号的跨重启实测：

• 当前 upstream browser-guests.ts 给工作区创建随机、非 persist: 分区；挂载 guest 时校验 lease、owner 和 partition。插件直接改成持久分区会被拒绝，不能仅改自己的 UI 来实现。
• DesktopBrowserBridge 目前只有 acquire / release / onOpenRequested，没有持久会话选择或同 tab 操作接口。因此“Browser UI 是插件”不等于“第三方插件已获得底层 session 能力”。如果已有受支持的入口，请纠正并指向文档。

社区方案很有参考价值，但需要区分载体（以下均为非官方、独立维护，不是官方推荐，也不代表已在此版本验证兼容）：

• #165 / dsh-browser、#9690 / Browser Connector：连接已有 Chrome tab、复用其登录态，解决的是外部浏览器控制。
• #8685 / Playwright persistent login：独立 profile 与状态保存/恢复；作者还解释了 session Cookie 和焦点抢占问题，值得参考，但不等同于为官方原生 Sidebar guest 开启持久化。
• #9896 / Crawshrimp Browser（前帖 #9871）：同包工具、侧栏实时预览、人工接管/归还，值得借鉴可见页面与 Agent 操作一致的体验；它使用自己的浏览器/预览路径，不能据此推断官方 guest 已有对应 API。该帖目标版本是 0.2.1-alpha.4。
• #9393 / Annotate & Add to chat：也在请求增强现有官方 Browser，而不是每个插件另造预览载体。可以与这里的 tab 身份和上下文接口协调，但批注不等于自动化授权。

ZCode 可借鉴什么，而不是照搬什么

ZCode Browser Settings 规格把用户流程组织为：开启内置浏览器控制 → 可选导入 Chrome 登录状态 → 在内置浏览器继续使用，并区分“清缓存”和“清全部站点数据”。规格明确使用 persist:zcode-embedded-browser；macOS/Linux 的导入是一次性 Cookie + LocalStorage，不是 HTTP cache、密码库或持续同步；该版本 Windows 导入入口隐藏，不能宣称跨平台完全一致。

更重要的是，ZCode 官方插件运行时边界明确把 Desktop view / CDP / IPC 留在宿主，普通插件不能自行声明这些高权限能力。参考点是“宿主提供受控能力，插件组合交互和工具”，不是“装任意插件就能绕过 native 限制”。 以上是其公开源码/规格的参考，不是对所有发布版本和真实网站的验收结论。

想请维护者确认的最小路径

1. 能否先提供宿主拥有的、用户明确 opt-in 的持久 Browser session，并让插件通过公开的版本化 API 选择？保持工作区隔离，提供清晰的退出登录/清站点数据入口，默认策略由官方决定。
2. 后续能否让插件拿到受授权的准确 tab 身份，接入 read/click/fill 与人工接管，而不是另起一个看不见或不同登录态的浏览器？授权应可撤销，并在 workspace/session/tab 间校验归属；不需要暴露任意 Electron IPC 或把 Cookie/token 返回给模型。
3. “导入已有 Chrome 登录态”能否作为独立的后续 opt-in 功能评估？第一步只要支持在 app 内手动登录并持久保留即可，不要求复制完整 Chrome profile，也不要求保证网站 session Cookie 永不过期。

若官方方向是不支持原生 guest 持久化，也希望文档/插件设置明确区分 外部浏览器连接 / 插件自有浏览器预览 / 官方原生 Browser，以及各自是否支持登录保留与同 tab 工具，避免用户把它们当成同一个功能。

English summary: Please support an opt-in, host-owned persistent session for the existing in-app Browser, consumable by plugins without patching the desktop app. External Chrome connectors and plugin-owned live previews solve adjacent but different workflows. ZCode is useful UX/ownership prior art, not evidence that an ordinary plugin can implement privileged persistence by itself. Same-tab tools and optional Chrome login import can follow separately. Is there an existing supported API, or a preferred extension design for this?