@michengai/dsh-btw 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.1.1] - 2026-09-06
+
+- Limit each session to 20 side-question bubbles. At capacity, close the oldest completed bubble before accepting a new question; failed closure preserves answers and the current input with a localized message.
+- Show localized retry messages when cleanup fails during closure and keep host error details in logs.
+- Preserve completed answers when resource cleanup fails, with close retries still available.
+- Bound startup cancellation and cleanup waits while retaining ownership of late child agents. Cleanup errors no longer block plugin unload, and unreleased children remain protected from tool execution.
+- Retain recent bubbles per session so questions in another session cannot evict answers. Failed cleanup during eviction keeps the bubble available for retry.
+- Format the community notice consistently as a blockquote in both READMEs.
+
 ## [0.1.0] - 2026-09-06
 
 - Add one-shot `/btw` questions that inherit completed turns from the main session and answer without executing tools.

package/CHANGELOG.zh-CN.md

@@ -1,5 +1,16 @@
 # 更新日志
 
+## [未发布]
+
+## [0.1.1] - 2026-09-06
+
+- 限制每个会话最多保留 20 个旁问气泡；满额先关闭最旧的已完成气泡，成功后接收新问题，失败则保留答案和当前输入并显示中英文提示。
+- 关闭清理失败时显示本地化重试提示，宿主错误详情仅记录日志。
+- 修复资源清理失败覆盖已完成答案的问题，保留关闭重试能力。
+- 为启动取消和资源清理增加有界等待，继续接管迟到的子代理；卸载异常不再阻塞插件退出，未释放子代理仍受工具保护。
+- 按会话保留最近的旁问气泡，避免其他会话的提问挤掉答案；淘汰时清理失败会保留气泡供重试。
+- 将中英文 README 的社区说明统一为引用块格式。
+
 ## [0.1.0] - 2026-09-06
 
 - 新增 `/btw` 一次性旁问，继承主会话已完成回合，只回答、不执行工具。

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/branding/dsh-btw-banner.png" alt="DSH BTW" width="100%">
+</p>
+
 <div align="center">
 
 # DSH BTW
@@ -12,23 +16,19 @@
 
 </div>
 
-Type `/btw your question` in the existing chat composer to get an answer based on your conversation's context. Answers appear in independent bubbles above the composer, ready for a quick explanation, recap, or follow-up question.
-
-DSH BTW is a community-maintained plugin for DSH Web and desktop apps that host the Web client. It does not occupy the sidebar, require Codex UI, or open a separate page.
+> DSH BTW is a community-maintained DeepSeek Harness plugin, not an official DeepSeek AI product. Type `/btw your question` in the current conversation to get a context-aware answer in an independent bubble without interrupting the main task. Supports DSH Web and desktop apps that include DSH Web.
 
 ## Features
 
-- **Context-aware questions**: each question starts a one-shot child agent that inherits completed turns from the main session.
-- **Answers only**: all tools are disabled. The agent cannot read new files, browse the web, run commands, or edit code.
+- **Context-aware questions**: explain concepts, recap conclusions, or ask a quick question about the current conversation.
+- **Answers only**: no reading new files, browsing the web, running commands, or editing code.
 - **Independent answer bubbles**: render Markdown, copy answers, collapse, expand, and close individual bubbles. Multiple answers can stay visible.
-- **Separate from the main task**: answers are not added to the main model's history, and previous side questions do not become context for later ones.
-- **Cancellation and cleanup**: closing a running bubble cancels only that question. Cleanup failures remain visible so closing can be retried.
+- **Keep the main task going**: side questions are answered separately and do not add answers to the main conversation.
+- **Cancel anytime**: close a bubble while it is answering to cancel that question.
 - **Themes and languages**: follow DSH light and dark themes and switch between Chinese and English UI.
 
 ## Screenshots
 
-These screenshots were provided by the user from the actual DSH dark interface. Model responses shown in them illustrate the bubble UI only.
-
 ### Side questions in stock DSH
 
 The main conversation stays in place, with the side answer above the composer.
@@ -49,72 +49,43 @@ Each answer has its own copy, collapse or expand, and close controls in the uppe
 
 ## Prerequisites
 
-- A working DeepSeek Harness Web installation with `dsh` available in PowerShell.
-- The development baseline is DSH `0.1.2-rc.1`. The host must provide a `fork` child agent with context inheritance, tool filtering, and persona support.
-- Source builds require Node.js 22+ and npm.
-- Examples use the `web` profile; replace it with your target profile.
+- An installed copy of DeepSeek Harness. The supported baseline is `0.1.2-rc.1`.
+- Node.js 22+ and `dsh` available in your terminal.
 
 ## Installation
 
-Install from npm, local source, or a built package.
+Examples use the `web` profile; replace it with your target profile. Disable other plugins that provide `/btw` before installing.
 
-Source repository: <https://github.com/MichengAI/dsh-btw>. Download `.tgz` packages from [Releases](https://github.com/MichengAI/dsh-btw/releases).
-
-### From npm
+### From npm (Recommended)
 
 ```powershell
 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 $OutputEncoding = [System.Text.Encoding]::UTF8
 
 dsh plugin --profile web add @michengai/dsh-btw@latest --registry=https://registry.npmjs.org/
-dsh --profile web --dump-config
 ```
 
-Use `@0.1.0` instead of `@latest` to pin the first release. Reload DSH after installation as described below.
-
-### From local source
-
-Run from the project root:
-
-```powershell
-[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
-$OutputEncoding = [System.Text.Encoding]::UTF8
-
-npm ci --ignore-scripts
-npm run build
-dsh plugin --profile web add . --ignore-scripts
-dsh --profile web --dump-config
-```
-
-Confirm that the configuration includes `michengai-btw`. A local directory installation reads the package metadata and `cordis.patch.yml`; do not copy `lib` separately.
-
 ### From a package archive
 
-Build an archive with `npm pack` from the project root, then install it:
+Download a `.tgz` from [Releases](https://github.com/MichengAI/dsh-btw/releases). Run this command from the download directory, replacing the filename with your downloaded version:
 
 ```powershell
 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 $OutputEncoding = [System.Text.Encoding]::UTF8
 
-npm pack
 dsh plugin --profile web add .\michengai-dsh-btw-0.1.0.tgz --ignore-scripts
-dsh --profile web --dump-config
 ```
 
-For an existing `.tgz`, substitute its path in the installation command. Disable other plugins that claim `/btw` before installing.
-
 ### Reloading
 
-DSH Codex Desktop may automatically reload its service when plugin configuration changes. Install or update after current tasks have finished. Other DSH Web launch methods require a manual restart.
-
-Rebuilding a linked plugin does not reload the backend. The current host's `patchReload: live` watches configuration, while backend HMR with `root: []` does not watch plugin JavaScript. The frontend can show new labels while the backend still serves the old command directory. Use the desktop app's reload action, or restart the relevant `dsh web` process, after tasks finish. Refreshing the browser alone does not update backend code.
+Install or update after current tasks finish, as desktop apps may reload automatically. If the change has not taken effect, use the desktop app's reload action or restart the `dsh web` service. Refreshing the browser alone is not enough.
 
 ## Usage
 
 In a conversation with existing context, enter:
 
 ```text
-/btw Why does the proposed design use a one-shot child agent?
+/btw Summarize the proposed plan in one sentence.
 ```
 
 | Goal | Action |
@@ -129,25 +100,10 @@ In a conversation with existing context, enter:
 
 Use the regular conversation to run commands, edit code, or continue the main task. BTW can only answer using existing context.
 
-Arrow-key input history belongs to Codex UI. BTW does not collect input history, access history storage, or bind arrow keys. Installing BTW alone adds side questions only.
+### Usage Notes
 
-## Compatibility and Boundaries
-
-The development baseline is DSH `0.1.2-rc.1`. The host needs commands, tools, subagents, and a fork provider supporting tool filtering, persona, and inherited context. Requests fail when these capabilities are unavailable. The client needs conversation, input-trigger, chat, api-remotes, locale, and host theme tokens.
-
-The child agent receives an empty tool allowlist. An execution guard also rejects all tools, including `run_code` and tools registered within child scopes.
-
-Forks inherit completed turns, excluding the turn currently being generated. Disposing a child agent does not delete host audit logs. Command results are not added to the main model history, but the host may retain command and child-agent records.
-
-Internal commands `btw-run` and `btw-close` are hidden from the command directory. They use the host's session RPC rather than adding HTTP endpoints. Users only need `/btw` and the bubble controls.
-
-`btw-run` accepts JSON `{ id, question, locale? }`. Supported locales are `zh` and `en`; omission defaults to Chinese for older clients, and other languages fall back to English. The response uses the host command's `{ kind, text }` format. `btw-close` accepts the raw request identifier; cleanup errors retain the request's language.
-
-Each question is limited to 8,000 characters, with a 90-second timeout and at most eight concurrent requests.
-
-Bubbles are stored in client memory only and are not restored after a refresh. Appearance follows the current DSH theme, independently of the operating system's dark-mode preference. UI translations update through the host locale service; server messages use the language at submission time. Model answers and original external errors are not translated.
-
-Local installation and outstanding acceptance checks are tracked in [Current Status](docs/00-交接入口/02-当前状态.md). Runtime and simulated-host tests do not replace actual DSH model and interaction checks.
+- Each question is independent and uses completed content from the main conversation at the time you ask. It does not include an answer still being generated or previous side questions.
+- Bubbles are not restored after refreshing the page. Copy any answers you want to keep first.
 
 ## Uninstallation
 
@@ -170,34 +126,13 @@ npm ci --ignore-scripts
 npm run check
 ```
 
-`npm run check` runs type checking, unit and release-script tests, and a build. `npm run dev` provides a simulated host with mock answers for development, without connecting to a real model. DSH remains the actual plugin entry point. Theme CSS and LocaleRuntime come from the matching official development dependencies.
+`npm run check` runs type checking, tests, and a build. After building, use `npm run test:browser` for browser tests; Microsoft Edge is required locally. `npm run dev` provides a UI preview with mock answers.
 
-`npm run test:browser` checks bubbles, cancellation, narrow layouts, Markdown, themes, contrast, language switching, and the absence of arrow-key interception.
-
-Build before running browser tests. Playwright manages `npm run dev` automatically and uses Microsoft Edge locally and Chromium in CI. `tests/host.test.ts` loads the host from the `node_modules` directory specified by `DSH_RUNTIME_ROOT`, defaulting to `.dsh/profiles/node_modules` under the user's home directory. The two tests are explicitly skipped when that host is absent; they do not read credentials or configuration. CI points at this project's development dependencies and executes the runtime tests.
-
-`tests/command-visibility.test.ts` uses a real Typert Registry, Gateway, and command runtime to check directory filtering, execution, and unload restoration. An installed desktop runtime can also be tested by setting `DSH_DESKTOP_RUNTIME_ROOT`. Passing these tests does not prove that a running DSH process has reloaded the latest build.
+To install from source, run `dsh plugin --profile web add . --ignore-scripts` from the project directory, then reload DSH.
 
 ## References and Credits
 
-The side-question interaction was informed by [JasonQQ/dsh-btw-plugin](https://github.com/JasonQQ/dsh-btw-plugin), the close lifecycle by [kaieye/dsh-AIR](https://github.com/kaieye/dsh-AIR), and boundary handling by the Pi plugin below. This plugin is implemented independently.
-
-References from [`@narumitw/pi-btw` 0.57.0](https://pi.dev/packages/@narumitw/pi-btw) and its [source](https://github.com/narumiruna/pi-extensions/tree/b4981b29604945d67ce2ce04e0f769c62bce1f20/packages/pi-btw):
-
-- Snapshot context at question time instead of continuously following the main task. BTW uses a fork of completed turns.
-- Recheck cancellation and reject late answers. BTW checks cancellation and request identity on both client and server.
-- Do not write answers back to the main task by default. BTW only displays independent bubbles and does not bind history-navigation keys.
-
-Pi calls the model directly without tools; BTW uses one-shot child agents. Pi's full-screen TUI, multi-turn recovery, and write-back features are not included.
-
-## Project Documentation
-
-The engineering documents are maintained in Chinese:
-
-- [Reading Guide](docs/00-交接入口/00-阅读导航.md)
-- [Current Status](docs/00-交接入口/02-当前状态.md)
-- [Outstanding Work](docs/00-交接入口/03-待办与阻塞.md)
-- [Automated Testing and Publishing](docs/05-工程交付/01-自动发布.md)
+Interaction design was informed by [dsh-btw-plugin](https://github.com/JasonQQ/dsh-btw-plugin), [dsh-AIR](https://github.com/kaieye/dsh-AIR), and [pi-btw](https://pi.dev/packages/@narumitw/pi-btw). This plugin is implemented independently.
 
 ## License
 

package/README.zh-CN.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="assets/branding/dsh-btw-banner.png" alt="DSH BTW" width="100%">
+</p>
+
 <div align="center">
 
 # DSH BTW
@@ -12,23 +16,19 @@
 
 </div>
 
-在原有聊天输入框输入 `/btw 问题`，根据当前会话的已有上下文获取回答。答案显示在输入框上方的独立气泡中，方便临时解释概念、回顾结论或追问原因。
-
-DSH BTW 是社区维护的 DSH Web 插件，也可用于承载 Web 客户端的桌面容器。不占用侧边栏，不依赖 Codex UI，无需打开独立页面。
+> DSH BTW 是社区维护的 DeepSeek Harness 插件，并非 DeepSeek AI 官方产品。在当前会话中输入 `/btw 问题`，即可基于已有上下文获得独立气泡回答，不打断主任务。支持 DSH Web 及集成 DSH Web 的桌面应用。
 
 ## 功能概览
 
-- **上下文旁问**：每次提问创建一次性子代理，继承主会话已完成回合。
-- **只回答，不执行**：禁用全部工具，不读取新文件、联网、运行命令或修改代码。
+- **上下文旁问**：根据当前会话内容解释概念、回顾结论或回答临时问题。
+- **只回答，不执行**：不会读取新文件、联网、运行命令或修改代码。
 - **独立答案气泡**：支持 Markdown、复制、折叠、展开和关闭，可同时查看多条旁问。
-- **主任务保持独立**：答案不回填主模型历史，上一条旁问也不会成为下一条的上下文。
-- **取消与清理**：关闭运行中的气泡只取消对应旁问；清理失败时保留提示，支持再次关闭。
+- **不打断主任务**：旁问单独作答，答案不会写入主会话。
+- **随时取消**：关闭正在回答的气泡即可取消该旁问。
 - **主题与国际化**：跟随 DSH 浅色、深色主题，界面支持中文和英文切换。
 
 ## 界面预览
 
-以下为用户提供的实际 DSH 深色界面截图，图中模型回答仅用于展示气泡效果。
-
 ### 原生 DSH 中的旁问
 
 主会话保留在原来的位置，旁问答案位于输入框上方。
@@ -49,71 +49,42 @@ DSH BTW 是社区维护的 DSH Web 插件，也可用于承载 Web 客户端的
 
 ## 前置条件
 
-- 已能正常使用 DeepSeek Harness Web，并且可在 PowerShell 中执行 `dsh`。
-- 开发基线为 DSH `0.1.2-rc.1`，宿主需要支持继承上下文的 `fork` 子代理、工具过滤及 persona。
-- 从源码构建需要 Node.js 22+ 和 npm。
-- 以下命令使用 `web` profile，请按实际环境替换。
+- 已安装 DeepSeek Harness，适配版本为 `0.1.2-rc.1`。
+- Node.js 22+，可在终端执行 `dsh`。
 
 ## 安装
 
-支持从 npm、本地源码或构建包安装。
-
-源码仓库：<https://github.com/MichengAI/dsh-btw>。也可从 [Releases](https://github.com/MichengAI/dsh-btw/releases) 下载 `.tgz` 安装包。
+以下命令使用 `web` profile，请按实际环境替换。安装前停用其他提供 `/btw` 命令的插件。
 
-### 从 npm 安装
+### 从 npm 安装（推荐）
 
 ```powershell
 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 $OutputEncoding = [System.Text.Encoding]::UTF8
 
 dsh plugin --profile web add @michengai/dsh-btw@latest --registry=https://registry.npmjs.org/
-dsh --profile web --dump-config
-```
-
-将 `@latest` 替换为 `@0.1.0` 可固定首个版本。安装后按下文说明重新加载 DSH。
-
-### 从本地源码安装
-
-在本项目根目录执行：
-
-```powershell
-[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
-$OutputEncoding = [System.Text.Encoding]::UTF8
-
-npm ci --ignore-scripts
-npm run build
-dsh plugin --profile web add . --ignore-scripts
-dsh --profile web --dump-config
 ```
 
-检查配置中是否包含 `michengai-btw`。本地目录安装会读取包信息和 `cordis.patch.yml`，无需手工复制 `lib`。
-
 ### 从安装包安装
 
-在本项目根目录执行 `npm pack` 生成安装包，然后安装：
+从 [Releases](https://github.com/MichengAI/dsh-btw/releases) 下载 `.tgz` 文件，在下载目录执行以下命令，将文件名替换为实际版本：
 
 ```powershell
 [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
 $OutputEncoding = [System.Text.Encoding]::UTF8
-npm pack
 dsh plugin --profile web add .\michengai-dsh-btw-0.1.0.tgz --ignore-scripts
-dsh --profile web --dump-config
 ```
 
-已有 `.tgz` 文件时，直接将安装命令中的路径替换为该文件路径。安装前停用其他占用 `/btw` 的插件。
-
 ### 重新加载
 
-DSH Codex Desktop 可能在检测到插件变更后自动重载服务，请在当前任务结束后安装或更新。其他 DSH Web 启动方式需要自行重启。
-
-本地开发链接的 JS 重新构建不等于后端已经重载。当前宿主的 `patchReload: live` 仅监听配置，后端 HMR 的 `root: []` 不监听插件 JS；前端可能已出现新文案，后端仍运行旧命令目录。升级后须等任务结束，重新加载实际使用的后端：桌面版使用其“重新加载”，独立 `dsh web` 则重启该命令对应的进程。仅刷新浏览器不能更新后端。
+请在当前任务结束后安装或更新，桌面应用可能自动重载。若未生效，使用桌面应用的“重新加载”，或重启 `dsh web` 服务；仅刷新浏览器不够。
 
 ## 使用
 
 在已有上下文的会话中输入：
 
 ```text
-/btw 刚才这个方案为什么采用一次性子代理？
+/btw 用一句话总结刚才的方案
 ```
 
 | 目标 | 操作 |
@@ -128,25 +99,10 @@ DSH Codex Desktop 可能在检测到插件变更后自动重载服务，请在
 
 若需要执行命令、修改代码或继续主任务，请通过普通会话提交。BTW 只能依据已有上下文作答。
 
-上下键输入历史已迁至 Codex UI。本插件不再采集输入历史、访问历史存储或绑定上下键；单独安装只提供 BTW 旁问。
-
-## 兼容与边界
-
-开发基线为 DSH `0.1.2-rc.1`。需要宿主装配 commands、tools、subagents 及 fork provider，且 provider 必须支持工具过滤、persona 与上下文继承；缺少能力时拒绝启动。客户端需要 conversation、input-trigger、chat、api-remotes、locale 模块及宿主主题令牌。
-
-子代理使用空工具白名单，并由执行层 guard 拒绝全部工具，包括 `run_code` 和子作用域自注册工具。
-
-fork 继承的是已完成回合，主任务正在生成的回合不包含在内。一次性子代理的释放不等于删除宿主的审计日志。命令结果不加入主模型历史，但宿主仍可保存命令及子代理记录。
-
-内部传输命令为 `btw-run` 和 `btw-close`，从命令目录中隐藏；用户只需使用 `/btw` 和气泡关闭按钮。它们使用宿主会话 RPC，未增加 HTTP 接口。
-
-`btw-run` 的 JSON 请求为 `{ id, question, locale? }`，`locale` 支持 `zh`、`en`，省略时兼容旧客户端按中文处理；其他语言回退英文。返回仍为宿主命令的 `{ kind, text }`。`btw-close` 继续接受原始请求标识，清理错误保留该请求的语言。
-
-单次问题最多 8000 字符、90 秒超时、最多同时处理 8 个请求。
+### 使用说明
 
-气泡仅保存在客户端内存中，刷新页面后不恢复。外观跟随 DSH 当前主题，不单独读取系统深色偏好。界面语言通过宿主 locale 服务即时切换，服务器提示使用提交时的语言；模型回答和外部原始错误不翻译。
-
-本机安装状态和待验收事项统一记录在[当前状态](docs/00-交接入口/02-当前状态.md)，运行时与模拟宿主测试不能代替实际 DSH 的模型和交互验收。
+- 每次旁问相互独立，参考的是提问时主会话已完成的内容，不包含正在生成的回答或之前的旁问。
+- 刷新页面后气泡不会保留，需要保存的答案请先复制。
 
 ## 卸载
 
@@ -168,32 +124,13 @@ npm ci --ignore-scripts
 npm run check
 ```
 
-`npm run check` 执行类型检查、单元测试和构建。`npm run dev` 仅提供开发用模拟宿主，回答为模拟数据，不连接真实模型；实际使用入口始终是 DSH。主题 CSS 和 LocaleRuntime 来自同版本官方开发依赖。
-
-运行 `npm run test:browser` 验证气泡、取消、窄屏、Markdown、主题切换、对比度、语言切换及不再拦截上下键。
+`npm run check` 执行类型检查、测试和构建。构建后可运行 `npm run test:browser` 做浏览器测试，本地需要 Microsoft Edge。`npm run dev` 提供使用模拟回答的界面预览。
 
-浏览器测试需要先构建，Playwright 自动管理 `npm run dev`，本地默认使用已安装的 Microsoft Edge，CI 使用 Chromium。`tests/host.test.ts` 从 `DSH_RUNTIME_ROOT` 指定的 `node_modules` 读取宿主；默认读取用户目录下 `.dsh/profiles/node_modules`，不存在时明确跳过这 2 项测试，不会读取凭据或配置。CI 指向本项目开发依赖，实际执行运行时用例。
-
-`tests/command-visibility.test.ts` 使用真实 Typert Registry、Gateway 和命令运行时验证 RPC 目录、执行及卸载恢复；同时检查本机可用的桌面运行时，其目录可用 `DSH_DESKTOP_RUNTIME_ROOT` 覆盖。通过该测试仍需确认运行中的 DSH 已重新加载构建产物。
+从源码安装时，在项目目录执行 `dsh plugin --profile web add . --ignore-scripts`，然后重新加载 DSH。
 
 ## 参考与致谢
 
-参考 [JasonQQ/dsh-btw-plugin](https://github.com/JasonQQ/dsh-btw-plugin) 的旁问交互、[kaieye/dsh-AIR](https://github.com/kaieye/dsh-AIR) 的关闭流程，以及下述 Pi 插件的边界处理，代码独立实现。
-
-参考 [`@narumitw/pi-btw` 0.57.0](https://pi.dev/packages/@narumitw/pi-btw) 的 [源码](https://github.com/narumiruna/pi-extensions/tree/b4981b29604945d67ce2ce04e0f769c62bce1f20/packages/pi-btw)：
-
-- 将旁问上下文限定为提问时的快照，避免跟随主任务持续变动。本插件通过 fork 继承已完成回合。
-- 取消后再次检查信号，拒收迟到答案。本插件前后端都按请求标识检查取消状态。
-- 默认不回填主任务。本插件只展示独立气泡，不绑定历史导航按键。
-
-Pi 使用无工具的直接模型调用；本插件仍按约定使用一次性子代理。未引入其全屏 TUI、多轮恢复或回填主任务功能。
-
-## 项目文档
-
-- [阅读导航](docs/00-交接入口/00-阅读导航.md)
-- [当前状态](docs/00-交接入口/02-当前状态.md)
-- [待办与阻塞](docs/00-交接入口/03-待办与阻塞.md)
-- [自动测试与发布](docs/05-工程交付/01-自动发布.md)
+交互设计参考 [dsh-btw-plugin](https://github.com/JasonQQ/dsh-btw-plugin)、[dsh-AIR](https://github.com/kaieye/dsh-AIR) 和 [pi-btw](https://pi.dev/packages/@narumitw/pi-btw)，代码独立实现。
 
 ## 许可证
 

package/lib/client.js

@@ -393,6 +393,7 @@ var zh = {
   "error.empty": "\u8BF7\u8F93\u5165\u65C1\u95EE\u5185\u5BB9\u3002",
   "error.length": "\u65C1\u95EE\u6700\u591A\u652F\u6301 8000 \u4E2A\u5B57\u7B26\u3002",
   "error.capacity": "\u6B63\u5728\u5904\u7406\u7684\u65C1\u95EE\u8F83\u591A\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002",
+  "error.bubbleCapacity": "\u5F53\u524D\u4F1A\u8BDD\u7684\u65C1\u95EE\u6C14\u6CE1\u5DF2\u8FBE\u4E0A\u9650\uFF0C\u8BF7\u5148\u5173\u95ED\u65E7\u6C14\u6CE1\uFF1B\u5173\u95ED\u5931\u8D25\u7684\u6C14\u6CE1\u53EF\u91CD\u8BD5\u3002",
   "error.close": "\u5173\u95ED\u5931\u8D25\uFF0C\u53EF\u91CD\u8BD5\u3002{detail}",
   "error.requestLength": "\u65C1\u95EE\u5185\u5BB9\u8FC7\u957F\u3002",
   "error.request": "\u65C1\u95EE\u8BF7\u6C42\u65E0\u6548\u3002",
@@ -404,7 +405,8 @@ var zh = {
   "error.timeout": "\u65C1\u95EE\u8D85\u65F6\uFF0C\u5DF2\u53D6\u6D88\u3002",
   "error.incomplete": "\u65C1\u95EE\u672A\u5B8C\u6210\uFF08{reason}\uFF09\u3002{detail}",
   "error.noText": "\u6A21\u578B\u672A\u8FD4\u56DE\u6587\u5B57\u56DE\u7B54\u3002",
-  "error.cleanup": "\u8D44\u6E90\u6E05\u7406\u5931\u8D25\uFF0C\u8BF7\u518D\u6B21\u5173\u95ED\u91CD\u8BD5\u3002{detail}"
+  "error.cleanup": "\u8D44\u6E90\u6E05\u7406\u5931\u8D25\uFF0C\u8BF7\u518D\u6B21\u5173\u95ED\u91CD\u8BD5\u3002{detail}",
+  "error.cleanupTimeout": "\u8D44\u6E90\u91CA\u653E\u4ECD\u672A\u5B8C\u6210\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u5173\u95ED\u3002"
 };
 var en = {
   "locale.id": "en",
@@ -428,6 +430,7 @@ var en = {
   "error.empty": "Enter a side question.",
   "error.length": "Side questions are limited to 8,000 characters.",
   "error.capacity": "Too many side questions are running. Try again shortly.",
+  "error.bubbleCapacity": "This session has reached its bubble limit. Close older bubbles first; retry any failed closures.",
   "error.close": "Could not close. Try again. {detail}",
   "error.requestLength": "The side question request is too long.",
   "error.request": "Invalid side question request.",
@@ -439,7 +442,8 @@ var en = {
   "error.timeout": "The side question timed out and was cancelled.",
   "error.incomplete": "The side question did not complete ({reason}).{detail}",
   "error.noText": "The model returned no text.",
-  "error.cleanup": "Cleanup failed. Close again to retry. {detail}"
+  "error.cleanup": "Cleanup failed. Close again to retry. {detail}",
+  "error.cleanupTimeout": "Resources are still being released. Try closing again shortly."
 };
 function translate(locale = "zh") {
   const dictionary = locale === "zh" ? zh : en;
@@ -455,6 +459,7 @@ var CLOSE_COMMAND = "btw-close";
 var MAX_QUESTION_LENGTH = 8e3;
 
 // src/client/bubbles.ts
+var MAX_BUBBLES_PER_SESSION = 20;
 var BubbleStore = class {
   constructor(transport, t = translate()) {
     this.transport = transport;
@@ -464,21 +469,42 @@ var BubbleStore = class {
   listeners = /* @__PURE__ */ new Set();
   active = /* @__PURE__ */ new Map();
   closing = /* @__PURE__ */ new Map();
+  admitting = /* @__PURE__ */ new Set();
+  disposed = false;
   getSnapshot = () => this.snapshot;
   subscribe = (listener) => {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
   };
-  ask(sessionId, question) {
+  /** 返回已接收请求的标识；满额先等待旧气泡关闭，失败时拒绝且不发送新问题。 */
+  async ask(sessionId, question) {
+    if (this.disposed) throw new Error(this.t("error.stopped"));
     if (!question.trim()) throw new Error(this.t("error.empty"));
     if (question.length > MAX_QUESTION_LENGTH) throw new Error(this.t("error.length"));
+    if (this.admitting.has(sessionId)) throw new Error(this.t("error.bubbleCapacity"));
+    if (this.active.size >= 8) throw new Error(this.t("error.capacity"));
+    const sessionBubbles = this.snapshot.filter((item) => item.sessionId === sessionId);
+    if (sessionBubbles.length >= MAX_BUBBLES_PER_SESSION) {
+      const oldest = sessionBubbles.find((item) => !this.active.has(item.id) && !this.closing.has(item.id) && !item.closeFailed);
+      if (!oldest) throw new Error(this.t("error.bubbleCapacity"));
+      this.admitting.add(sessionId);
+      let timer;
+      try {
+        await Promise.race([this.close(oldest.id), new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(this.t("error.bubbleCapacity"))), 5e3);
+        })]);
+      } finally {
+        clearTimeout(timer);
+        this.admitting.delete(sessionId);
+      }
+    }
+    if (this.disposed) throw new Error(this.t("error.stopped"));
+    if (this.snapshot.filter((item) => item.sessionId === sessionId).length >= MAX_BUBBLES_PER_SESSION) throw new Error(this.t("error.bubbleCapacity"));
     if (this.active.size >= 8) throw new Error(this.t("error.capacity"));
     const id = crypto.randomUUID();
     const controller = new AbortController();
     this.active.set(id, controller);
-    const settled = this.snapshot.filter((item) => !this.active.has(item.id)).slice(-19);
-    const running = this.snapshot.filter((item) => this.active.has(item.id));
-    this.publish([...settled, ...running, { id, sessionId, question, answer: "", phase: "answering" }]);
+    this.publish([...this.snapshot, { id, sessionId, question, answer: "", phase: "answering" }]);
     void Promise.resolve().then(() => this.transport.run(sessionId, id, question, controller.signal)).then((result) => {
       if (controller.signal.aborted || this.closing.has(id)) return;
       this.update(id, { phase: result.kind === "success" ? "done" : "error", answer: result.kind === "success" ? result.text : "", error: result.kind === "error" ? result.text : void 0 });
@@ -509,6 +535,7 @@ var BubbleStore = class {
     return operation;
   }
   async dispose() {
+    this.disposed = true;
     await Promise.all(this.snapshot.map((item) => this.close(item.id)));
   }
   update(id, patch2) {
@@ -13394,7 +13421,7 @@ function apply(ctx) {
     submit: async (args, _actx, images) => {
       if (images.length) return { kind: "error", text: t("error.images") };
       try {
-        store.ask(sessionId, args.trim());
+        await store.ask(sessionId, args.trim());
         return { kind: "success" };
       } catch (error) {
         return { kind: "error", text: error instanceof Error ? error.message : String(error) };