Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

fix(web): 沙箱后端的安装没落地时,对话框留着原因,重试只装还缺的包

lmlihenged5599796313
diff --git a/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.md b/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.md
new file mode 100644
index 00000000..a0f36ac0
--- /dev/null
+++ b/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.md
@@ -0,0 +1,58 @@
+# A sandbox-backend install that did not land keeps its prompt open, with the reason and the retry
+
+- **Date:** 2026-11-06
+- **Type:** fix
+- **Scope:** `web`
+- **Breaking:** no
+
+[中文](2026-11-06-sandbox-backend-install-refusal.zh.md)
+
+The Sandbox card in Settings offers to install this OS's default sandbox backends the moment its
+switch is turned on over a machine that reports none. That install can end without the machine
+getting a backend: a package the server did list but the process could not load, or a request that
+never got an answer (the packages after it are not tried). The dialog used to close as soon as the
+request left, and the only account of the failure was a notification that dismissed itself after
+six seconds — over a card still reading "no backend for this OS".
+
+The prompt now closes on a run that installed everything, not on the request. When something is
+left behind it stays open with the reason under its own question (`role="alert"`, the server's
+words for a package that would not load, the error code's localized sentence for a request that
+failed), names the packages still missing, and offers only those — its own Install button is the
+retry, and retrying does not install again what already landed, because every install reloads the
+server's plugins and stops agent runs in progress. The card's live parts are read again either way,
+so what did install shows.
+
+## Details
+
+- `packages/web/src/features/settings/sandbox-backend-refusal.ts` (new):
+ `backendInstallRefusal(failures, stopped, remaining)` — the pure decision, so which sentence
+ appears is in one place and testable without the page.
+- `packages/web/src/features/settings/plugins-section.tsx`: `installOffered()` collects the run's
+ failures instead of toasting them, re-reads the card's live parts, and closes the prompt only
+ when nothing is left; otherwise it narrows the offer to the missing packages and keeps the
+ sentence. The "no Project" precondition also stays in the prompt now (it had the same six-second
+ problem).
+- `packages/web/src/features/settings/sandbox-backend-prompt.tsx`: one new `refusal` prop, drawn
+ in `ConfirmModal`'s refusal slot under the question.
+- `packages/web/src/lib/strings{,-en}.ts`: a new pair, `sandboxBackendPrompt.installStopped(reason)`
+ and `sandboxBackendPrompt.installRefused(reasons, missing)`.
+
+## Tests
+
+- `packages/web/test/sandbox-backend-refusal.test.ts` (new, 8 cases): nothing to say when every
+ package installed; a package that would not load is quoted in the server's words; a request that
+ never answered is read through its code's localized sentence, never the wire's English; only the
+ missing packages are named; a reason that already ends a sentence does not double its full stop;
+ several reasons are kept; a value this codebase raised is shown as it wrote it; the active
+ language is followed.
+- `packages/web/e2e/sandbox-backend-install-refusal.spec.mjs` (new, 3 cases, real server + real
+ browser): with the install stubbed to `internal`, the prompt stays open with the sentence and no
+ toast carries it, **7 seconds later** it is still there with a live Install button, and pressing
+ it again lands the package and closes the prompt; a package that installed but would not load is
+ quoted in the server's words; a two-package run that stopped on the second offers only the
+ second, and the retry posts only that one.
+
+## Compatibility
+
+No API, wire format or stored data changes; no new dependency. Which words appear for an error code
+is unchanged (`refusalText`, 7.19's rule).
diff --git a/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.zh.md b/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.zh.md
new file mode 100644
index 00000000..587a59d0
--- /dev/null
+++ b/changelog/unreleased/2026-11-06-sandbox-backend-install-refusal.zh.md
@@ -0,0 +1,45 @@
+# 沙箱后端的安装没落地时,对话框留着:原因在框里,重试也在框里
+
+- **日期:** 2026-11-06
+- **类型:** fix
+- **范围:** `web`
+- **破坏性:** 否
+
+[English](2026-11-06-sandbox-backend-install-refusal.md)
+
+设置里的沙盒卡片,在开关被打开、而机器报告没有适用于其操作系统的沙盒后端时,会问要不要装这个系统的
+默认后端。那次安装可能没让机器拿到后端 —— 服务端列出了这个包、但进程装不上,或者请求根本没得到答复
+(它之后的包也不再尝试)。对话框过去一发出请求就关掉,唯一的交代是一条六秒后自己消失的通知 —— 而卡片
+上仍写着「没有适用于其操作系统的后端」。
+
+现在对话框在**全部装好**时关闭,而不是在请求发出时关闭。有东西没装上,它就留着:原因画在它自己的问题
+下面(`role="alert"`,装不上的包用服务端自己的原话、失败的请求按错误码念本地化的那句),点名**还没装
+上的包**,并且只提供这些 —— 它自己的「安装」按钮就是重试,重试也不会把已经装好的再装一遍,因为每次
+安装都会重新装载服务器的插件、中止所有项目中正在进行的 Agent 运行。无论成败,卡片上那些实时状态都会
+重读一次,所以真装上的东西看得见。
+
+## 明细
+
+- `packages/web/src/features/settings/sandbox-backend-refusal.ts`(新):
+ `backendInstallRefusal(failures, stopped, remaining)` —— 纯判断,念哪句话只在这一处,不依赖页面就能测。
+- `packages/web/src/features/settings/plugins-section.tsx`:`installOffered()` 把这一轮失败收起来不再
+ 走通知,随后重读卡片的实时状态,只在什么都不剩时关闭对话框;否则把「要装的包」收窄成还缺的那几个,
+ 并留下那句话。「请先打开一个项目」那条前提也改成留在对话框里(它原本有同样的六秒问题)。
+- `packages/web/src/features/settings/sandbox-backend-prompt.tsx`:多一个 `refusal` 属性,画在
+ `ConfirmModal` 的拒绝槽里、问题的下面。
+- `packages/web/src/lib/strings{,-en}.ts`:一对新文案 `sandboxBackendPrompt.installStopped(reason)` 与
+ `sandboxBackendPrompt.installRefused(reasons, missing)`。
+
+## 测试
+
+- `packages/web/test/sandbox-backend-refusal.test.ts`(新,8 条):全部装好时无话可说;装不上的包用服务端
+ 原话;失败的请求按错误码念本地化句子、不带线上英文原文;只点名还缺的包;已经有句号的理由不会叠成
+ 两个句号;多条理由都留着;本仓自己抛的值按原话念;跟着当前语言。
+- `packages/web/e2e/sandbox-backend-install-refusal.spec.mjs`(新,3 条,真服务端 + 真浏览器):安装桩成
+ `internal` 时对话框留着、原因在框里而不在通知区,**7 秒后**仍在且「安装」按钮可再按,重按之后包真的
+ 装上、对话框关闭;装上了但加载不了的包用服务端原话;两个包的这一轮卡在第二个时只提供第二个,重试只
+ 发这一个。
+
+## 兼容性
+
+不碰接口、线上格式与已存数据,不引入新依赖。错误码念哪句话没有变(`refusalText`,7.19 的规则)。
diff --git a/packages/web/e2e/sandbox-backend-install-refusal.spec.mjs b/packages/web/e2e/sandbox-backend-install-refusal.spec.mjs
new file mode 100644
index 00000000..401b2a36
--- /dev/null
+++ b/packages/web/e2e/sandbox-backend-install-refusal.spec.mjs
@@ -0,0 +1,244 @@
+/**
+ * Regression: when a run of the sandbox backends the Sandbox card offers does not leave the
+ * machine with one, the prompt that asked stays open and says why under its own question — and
+ * its Install button retries only what is still missing.
+ *
+ * The prompt asks one question the moment the card's switch is turned on over a machine that
+ * reports no backend for its OS. A run can end short: a package the server listed but the process
+ * could not load, or a request that never got an answer (the packages after it are not tried).
+ * The dialog used to close on the request anyway, and the only account of it was a toast that
+ * dismissed itself after six seconds — over a card still reading "no backend for this OS".
+ *
+ * Both halves are stubbed where the page's contract with the server is (`page.route`): the
+ * configuration it reads (one group with a switch and a backend report) and the install it sends
+ * (the deployment list read for the machine id, then each install). `state.refuse` picks the
+ * shape of the refusal, and turning it off is the retry.
+ */
+import { test, expect } from "@playwright/test";
+import { ADMIN_ID, ADMIN_PASSWORD, login } from "./auth.mjs";
+
+const BASE = process.env.BASE_URL;
+const MOCK = process.env.MOCK_URL;
+
+const BW = "@adelie/sandbox-bwrap";
+const DSH = "@adelie/sandbox-dsh";
+
+/** One group with a switch, a field behind it and the backend report that offers an install. */
+const ENTRY = {
+ name: "sandbox",
+ configuration: {
+ title: "Sandbox",
+ titleZh: "沙盒",
+ switch: "enabled",
+ properties: {
+ enabled: { type: "boolean", title: "Enable sandbox", titleZh: "启用沙盒" },
+ maskPaths: { type: "string", title: "Mask paths", titleZh: "掩码路径" },
+ },
+ },
+ values: {},
+ backend: { installed: false, recommended: [BW] },
+};
+
+/** What the page says when the request never answered, then what is left to install. */
+const NEVER_ANSWERED = `安装请求失败:服务器内部错误,请稍后重试。还没装上:${BW}。可以再点一次「安装」。`;
+
+/** Sign in as the seeded administrator and give the Project a model (the onboarding overlay). */
+async function ready(page) {
+ await login(page.request, ADMIN_ID, ADMIN_PASSWORD);
+ const projectId = (await (await page.request.get(`${BASE}/api/projects`)).json()).projects[0]
+ .projectId;
+ const put = await page.request.put(`${BASE}/api/projects/${projectId}/models`, {
+ data: {
+ defaultModel: { provider: "custom", modelId: "claude-4-8" },
+ models: [
+ {
+ provider: "custom",
+ modelId: "claude-4-8",
+ apiKey: "sk-mock",
+ baseUrl: MOCK,
+ contextWindow: 200000,
+ },
+ ],
+ },
+ });
+ expect(put.ok(), "put models").toBeTruthy();
+}
+
+/** The settings dialog, opened the way a person opens it: the user menu, then a page. */
+async function openSettings(page, section) {
+ // The user menu shares its name with the Project switcher, so take the last match (as chat.spec).
+ await page.getByRole("button", { name: ADMIN_ID }).last().click();
+ await page.getByRole("menuitem", { name: "设置", exact: true }).click();
+ const settings = page.getByRole("dialog", { name: "设置" });
+ await expect(settings).toBeVisible();
+ await settings.getByRole("button", { name: section, exact: true }).click();
+ return settings;
+}
+
+/** The toast stack by its own hook rather than by role: the modal marks the page aria-hidden. */
+function toasts(page) {
+ return page.locator('section[aria-label="通知"] button');
+}
+
+/** One row of the deployment list; `error` is what the page reads as a package that would not load. */
+function listed(specifier, error) {
+ return {
+ specifier,
+ active: error === undefined,
+ builtin: true,
+ modules: [],
+ replaces: [],
+ everywhere: true,
+ machines: [],
+ here: true,
+ ...(error === undefined ? {} : { error }),
+ };
+}
+
+function deployment(plugins) {
+ return {
+ plugins,
+ shipped: [BW, DSH],
+ file: ".project_config.toml",
+ machineId: "probe-machine",
+ restartPending: false,
+ };
+}
+
+/**
+ * Serve the configuration from the fixture and answer each install through `state.answer(pkg,
+ * n)`, which returns the response body or a status to refuse with. `state.posts` records what was
+ * sent, package by package, in order.
+ */
+async function stub(page, state) {
+ const answer = (route, body) =>
+ route.fulfill({ status: 200, contentType: "application/json", body: JSON.stringify(body) });
+ await page.route("**/api/admin/plugin-config", async (route) => {
+ if (route.request().method() !== "GET") return route.fallback();
+ return answer(route, { plugins: [state.entry] });
+ });
+ await page.route("**/api/projects/*/plugins/installed*", async (route) => {
+ if (route.request().method() === "GET") return answer(route, deployment(state.plugins));
+ if (route.request().method() !== "POST") return route.fallback();
+ const body = route.request().postDataJSON();
+ state.posts.push(body);
+ const answerOf = state.answer(body.specifier, state.posts.length - 1);
+ if (answerOf !== undefined) return answer(route, deployment(answerOf));
+ return route.fulfill({
+ status: 500,
+ contentType: "application/json",
+ body: JSON.stringify({ error: { code: "internal", message: "Internal server error" } }),
+ });
+ });
+}
+
+/** Turn the card's switch on, which is what asks the question under test. */
+async function ask(page, settings) {
+ const card = settings.locator('[data-plugin-config="sandbox"]');
+ await expect(card).toBeVisible();
+ await card.getByRole("switch", { name: "启用沙盒" }).click();
+ const prompt = page.getByRole("dialog", { name: "安装沙盒后端" });
+ await expect(prompt).toBeVisible();
+ return prompt;
+}
+
+test("a request that never answered keeps the prompt open with the reason and the retry", async ({
+ page,
+}) => {
+ await ready(page);
+ const state = {
+ entry: ENTRY,
+ plugins: [],
+ posts: [],
+ answer: () => undefined,
+ };
+ await stub(page, state);
+
+ await page.goto("/");
+ const settings = await openSettings(page, "插件");
+ const prompt = await ask(page, settings);
+ await expect(prompt.getByRole("alert")).toHaveCount(0);
+
+ await prompt.getByRole("button", { name: "安装", exact: true }).click();
+
+ // The dialog closes on the answer, not on the request: nothing installed, so it stays — with the
+ // reason under its question, naming the package the button retries.
+ await expect(prompt).toBeVisible();
+ await expect(prompt.getByRole("alert")).toHaveText(NEVER_ANSWERED);
+ expect(state.posts).toEqual([{ specifier: BW, machineId: "probe-machine" }]);
+ // The reason is not also a toast: one account of a refusal, next to the button that retries it.
+ await expect(toasts(page).filter({ hasText: "服务器内部错误" })).toHaveCount(0);
+
+ // Six seconds is how long a toast lives; this sentence and its button have to outlast it.
+ await page.waitForTimeout(7_000);
+ await expect(prompt.getByRole("alert")).toHaveText(NEVER_ANSWERED);
+ await expect(prompt.getByRole("button", { name: "安装", exact: true })).toBeEnabled();
+
+ // Retrying is the same button: the install lands, the prompt closes, and the sentence goes.
+ state.answer = () => [listed(BW)];
+ await prompt.getByRole("button", { name: "安装", exact: true }).click();
+ await expect(prompt).toHaveCount(0);
+ expect(state.posts).toEqual([
+ { specifier: BW, machineId: "probe-machine" },
+ { specifier: BW, machineId: "probe-machine" },
+ ]);
+ await expect(toasts(page).filter({ hasText: `已安装 ${BW}` })).toHaveCount(1);
+});
+
+test("a package that installed but would not load is quoted in the server's own words", async ({
+ page,
+}) => {
+ await ready(page);
+ const state = {
+ entry: ENTRY,
+ plugins: [],
+ posts: [],
+ answer: () => [listed(BW, "EACCES: permission denied, open '/usr/bin/bwrap'")],
+ };
+ await stub(page, state);
+
+ await page.goto("/");
+ const settings = await openSettings(page, "插件");
+ const prompt = await ask(page, settings);
+ await prompt.getByRole("button", { name: "安装", exact: true }).click();
+
+ await expect(prompt).toBeVisible();
+ await expect(prompt.getByRole("alert")).toHaveText(
+ `${BW} 加载失败:EACCES: permission denied, open '/usr/bin/bwrap'。还没装上:${BW}。可以再点一次「安装」。`,
+ );
+ await expect(toasts(page).filter({ hasText: "加载失败" })).toHaveCount(0);
+});
+
+test("a run that stopped halfway offers — and retries — only the package still missing", async ({
+ page,
+}) => {
+ await ready(page);
+ const state = {
+ entry: { ...ENTRY, backend: { installed: false, recommended: [BW, DSH] } },
+ plugins: [listed(BW)],
+ posts: [],
+ // The first package loads; the second request is the one that never answers.
+ answer: (pkg) => (pkg === BW ? [listed(BW)] : undefined),
+ };
+ await stub(page, state);
+
+ await page.goto("/");
+ const settings = await openSettings(page, "插件");
+ const prompt = await ask(page, settings);
+ await expect(prompt).toContainText(BW);
+ await expect(prompt).toContainText(DSH);
+ await prompt.getByRole("button", { name: "安装", exact: true }).click();
+
+ // Only what is left: the package that landed is not offered — and so not installed — again.
+ await expect(prompt.getByRole("alert")).toHaveText(
+ `安装请求失败:服务器内部错误,请稍后重试。还没装上:${DSH}。可以再点一次「安装」。`,
+ );
+ await expect(prompt).toContainText(DSH);
+ await expect(prompt).not.toContainText(BW);
+
+ // The retry posts that one package, and nothing else.
+ state.answer = () => [listed(BW), listed(DSH)];
+ await prompt.getByRole("button", { name: "安装", exact: true }).click();
+ await expect(prompt).toHaveCount(0);
+ expect(state.posts.map((p) => p.specifier)).toEqual([BW, DSH, DSH]);
+});
diff --git a/packages/web/src/features/settings/plugins-section.tsx b/packages/web/src/features/settings/plugins-section.tsx
index a7c0f552..1e04d7b9 100644
--- a/packages/web/src/features/settings/plugins-section.tsx
+++ b/packages/web/src/features/settings/plugins-section.tsx
@@ -61,13 +61,14 @@ import { ConfigHeading } from "./plugin-config-heading";
import { withLiveParts } from "./plugin-config-live";
import { pluginConfigStale, pluginConfigUnreadable } from "./plugin-config-read";
import { pluginSaveRefusal } from "./plugin-config-save";
+import { backendInstallRefusal } from "./sandbox-backend-refusal";
+import type { BackendInstallFailure, BackendInstallStop } from "./sandbox-backend-refusal";
import { SandboxBackendPrompt } from "./sandbox-backend-prompt";
import {
Button,
ConfirmModal,
NoticeStrip,
SettingsSection,
- toastError,
toastInfo,
toastSuccess,
} from "@adelie/ui";
@@ -140,9 +141,15 @@ export function PluginsSection({ focus }: { focus?: string } = {}) {
const [readError, setReadError] = useState<string | null>(null);
const nameOf = (id: string) => machineLabels.get(id) ?? id;
const projectId = useProject().currentProject?.projectId ?? null;
- /** The backend package the install prompt offers, while it is open. */
+ /** The backend packages the install prompt offers, while it is open. */
const [offered, setOffered] = useState<string[] | null>(null);
const [installing, setInstalling] = useState(false);
+ /**
+ * Why a run of those installs left packages behind, and which ones — drawn inside the prompt
+ * that asked, under the button that retries them (sandbox-backend-refusal.ts). Null when the
+ * last run installed everything, or before the first one.
+ */
+ const [installRefusal, setInstallRefusal] = useState<string | null>(null);
const adopt = (list: PluginConfigEntry[]) => {
setEntries(list);
@@ -367,56 +374,86 @@ export function PluginsSection({ focus }: { focus?: string } = {}) {
*/
const offerBackend = (entry: PluginConfigEntry) => {
const pkgs = backendToOffer(entry, machine ?? THIS_SERVER_KEY);
- if (pkgs !== null) setOffered(pkgs);
+ if (pkgs === null) return;
+ // A fresh question: the sentence under it belonged to the attempt before.
+ setInstallRefusal(null);
+ setOffered(pkgs);
};
const closePrompt = (dontAskAgain: boolean) => {
if (dontAskAgain) dismissBackendPrompt(machine ?? THIS_SERVER_KEY);
setOffered(null);
+ setInstallRefusal(null);
};
/**
* Installs the offered backends the way the Plugins page does, one after another: into this
* Project's table for the machine on screen only — this server's own machine id when the card
- * shows this server, so no other machine is asked to run it. A request that fails stops the
- * run and is reported; either way the prompt closes and the card's live parts (notices, the
- * backend report) are read again, so what did install shows; drafts being edited are kept.
+ * shows this server, so no other machine is asked to run it.
+ *
+ * The prompt closes on a run that installed everything, not on the request: a package the
+ * server listed but the process could not load, or a request that never answered, leaves the
+ * machine without the backend the card asked for — so the dialog stays open with that reason
+ * under its question, offering only the packages still missing, and its own Install button is
+ * the retry (a toast was the only account of a refusal before, gone six seconds later, over a
+ * card still reading "no backend for this OS"). Either way the card's live parts are read again,
+ * so what did install shows.
*/
const installOffered = async (dontAskAgain: boolean) => {
if (offered === null || installing) return;
if (projectId === null) {
- toastError(S.settings.sandboxBackendPrompt.noProject);
+ // The dialog that asked keeps its own precondition too: its button is where the next try is.
+ setInstallRefusal(S.settings.sandboxBackendPrompt.noProject);
return;
}
+ const pkgs = offered;
+ const installed: string[] = [];
+ const failures: BackendInstallFailure[] = [];
+ let stopped: BackendInstallStop | null = null;
+ setInstallRefusal(null);
setInstalling(true);
let target = machine;
await installInOrder(
- offered,
+ pkgs,
async (pkg) => {
const to = (target ??= (await api.getInstalledPlugins(projectId)).machineId);
const res = await api.installPlugin(projectId, pkg, to);
return res.plugins.find((p) => p.specifier === pkg)?.error;
},
{
- installed: (pkg) => toastSuccess(S.plugins.deploymentInstalledToast(pkg)),
- failed: (pkg, error) => toastError(S.plugins.deploymentFailedToast(pkg, error)),
- threw: (e) => toastError(apiErrorText(e)),
+ installed: (pkg) => {
+ installed.push(pkg);
+ toastSuccess(S.plugins.deploymentInstalledToast(pkg));
+ },
+ failed: (pkg, error) => failures.push({ pkg, error }),
+ threw: (e) => {
+ stopped = { error: e };
+ },
},
);
- closePrompt(dontAskAgain);
try {
const config = await api.adminGetPluginConfig(machine);
setEntries((prev) => withLiveParts(prev ?? [], config.plugins));
// The cards say what the machine answered: nothing is stale any more.
setReadError(null);
} catch (e) {
- // The package toasts said what installed, but the cards' notices, actions and backend
- // report are what the machine said before the install — a card that still reads "no
- // backend for this OS" is the worst answer, and a six-second toast over it was all that
- // said why (7.72). Say it where the cards are; opening the page again is the retry.
+ // The packages that did install are already in the Project's table, but the cards' notices,
+ // actions and backend report are what the machine said before the install — a card that
+ // still reads "no backend for this OS" is the worst answer, and a six-second toast over it
+ // was all that said why (7.72). Say it where the cards are; opening the page again is the
+ // retry.
setReadError(pluginConfigStale(machine === null ? null : nameOf(machine), apiErrorText(e)));
} finally {
setInstalling(false);
}
+ const remaining = pkgs.filter((p) => !installed.includes(p));
+ if (remaining.length === 0) {
+ closePrompt(dontAskAgain);
+ return;
+ }
+ // Only what is still missing: the retry must not install again what already landed, because
+ // every install reloads the server's plugins and stops agent runs in progress.
+ setOffered(remaining);
+ setInstallRefusal(backendInstallRefusal(failures, stopped, remaining));
};
// Only when there is another machine to pick: a single server has nothing to switch to.
@@ -614,6 +651,7 @@ export function PluginsSection({ focus }: { focus?: string } = {}) {
pkgs={offered}
machineName={machine === null ? S.plugins.thisServer : nameOf(machine)}
busy={installing}
+ refusal={installRefusal}
onInstall={(dontAskAgain) => void installOffered(dontAskAgain)}
onLater={(dontAskAgain) => {
if (!installing) closePrompt(dontAskAgain);
diff --git a/packages/web/src/features/settings/sandbox-backend-prompt.tsx b/packages/web/src/features/settings/sandbox-backend-prompt.tsx
index ce830d46..d38fa11f 100644
--- a/packages/web/src/features/settings/sandbox-backend-prompt.tsx
+++ b/packages/web/src/features/settings/sandbox-backend-prompt.tsx
@@ -6,6 +6,10 @@
* The answer never touches the switch: it stays on in the card either way, and the card's Save
* stores it. Installing goes through the Plugins page's own install, so it carries that page's
* cost, which the body says: the App is re-assembled, stopping runs in progress.
+ *
+ * A run that did not install everything keeps this card open — `refusal` carries the reason and
+ * the packages still missing (features/settings/sandbox-backend-refusal.ts), so the button that
+ * retries them is the one under the sentence rather than a toast that is gone before it is read.
*/
import { useState } from "react";
import { Checkbox, ConfirmModal, ICONS } from "@adelie/ui";
@@ -15,6 +19,7 @@ export function SandboxBackendPrompt({
pkgs,
machineName,
busy,
+ refusal,
onInstall,
onLater,
}: {
@@ -23,6 +28,8 @@ export function SandboxBackendPrompt({
/** The machine the card is editing, as the picker names it. */
machineName: string;
busy: boolean;
+ /** Why the last run left packages behind, and which ones — null when there is nothing to say. */
+ refusal: string | null;
onInstall: (dontAskAgain: boolean) => void;
onLater: (dontAskAgain: boolean) => void;
}) {
@@ -39,6 +46,7 @@ export function SandboxBackendPrompt({
cancelLabel={P.later}
onConfirm={() => onInstall(dontAsk)}
onClose={() => onLater(dontAsk)}
+ refusal={refusal === null ? undefined : refusal}
>
<div className="space-y-2 text-sm">
<p>{P.body(machineName, pkgs ?? [])}</p>
diff --git a/packages/web/src/features/settings/sandbox-backend-refusal.ts b/packages/web/src/features/settings/sandbox-backend-refusal.ts
new file mode 100644
index 00000000..3da76dfa
--- /dev/null
+++ b/packages/web/src/features/settings/sandbox-backend-refusal.ts
@@ -0,0 +1,62 @@
+/**
+ * The install prompt on the Sandbox card: the sentence it keeps when a run of backend packages
+ * did not leave the machine with what the switch needs, and why it is kept in the prompt instead
+ * of arriving as a toast.
+ *
+ * The prompt asks one question ("install this OS's default backends?") and its own Install
+ * button is the retry. A run can end without the backend: a package the server did list but the
+ * process could not load, or a request that never got an answer — after it the run stops and the
+ * later packages are not tried. Either way the machine is exactly as it was, the card behind the
+ * dialog still reads "no backend for this OS", and the only account of it was a notification that
+ * dismissed itself after six seconds (7.72's rule, applied to the dialog that asked).
+ *
+ * Two losses, named differently: a package that installed but failed to load is quoted with the
+ * server's own words for it, while a request that threw is read through `refusalText` — the rule
+ * every refusal slot in the app follows (7.19), so a localized code's sentence is used rather than
+ * the wire's English.
+ *
+ * What is *not* in the sentence is as important as what is: only the packages still missing are
+ * listed, because those are what the button behind the sentence retries. Naming a package that
+ * did land would invite installing it a second time, and every install reloads the server's
+ * plugins and stops agent runs in progress.
+ */
+import { refusalText } from "../../lib/api-error";
+import { S } from "../../lib/strings";
+
+/** A package the server listed but the process could not load, with the server's own words. */
+export interface BackendInstallFailure {
+ pkg: string;
+ error: string;
+}
+
+/**
+ * The run stopped on a request that never answered, so the packages after it were not tried —
+ * wrapped rather than passed as `unknown`, so a thrown `null` still reads as "it stopped".
+ */
+export interface BackendInstallStop {
+ error: unknown;
+}
+
+/**
+ * The line the prompt draws under its question, or null when there is nothing to say (every
+ * offered package installed). `remaining` is the offer minus what landed, in the order the run
+ * tried them — the same list the prompt goes on to show.
+ */
+export function backendInstallRefusal(
+ failures: readonly BackendInstallFailure[],
+ stopped: BackendInstallStop | null,
+ remaining: readonly string[],
+): string | null {
+ if (remaining.length === 0) return null;
+ const reasons = failures.map((f) => S.plugins.deploymentFailedToast(f.pkg, f.error));
+ if (stopped !== null) {
+ reasons.push(S.settings.sandboxBackendPrompt.installStopped(refusalText(stopped.error)));
+ }
+ // Each reason goes in as a bare sentence: the joined line supplies the punctuation, and some
+ // reasons already end one (a localized error code's own full stop) — keeping theirs would read
+ // as "…。;…" or, at the end, as a doubled full stop.
+ return S.settings.sandboxBackendPrompt.installRefused(
+ reasons.map((reason) => reason.replace(/[。.;;]+$/u, "")),
+ remaining,
+ );
+}
diff --git a/packages/web/src/lib/strings-en.ts b/packages/web/src/lib/strings-en.ts
index 08514c0d..43fb1e99 100644
--- a/packages/web/src/lib/strings-en.ts
+++ b/packages/web/src/lib/strings-en.ts
@@ -806,6 +806,16 @@ export const en: Strings = {
later: "Not now",
dontAsk: "Don't ask again for this machine",
noProject: "Open a Project first: the backend is installed into the current Project.",
+ /** The run stopped on a request that never answered — the reason, not a package's own. */
+ installStopped: (reason: string) => `The install request failed: ${reason}`,
+ /**
+ * What the prompt keeps after a run that left packages behind: the reasons it has (a package
+ * that would not load, a request that failed), then the ones still missing — they are what
+ * the Install button behind this sentence retries.
+ */
+ installRefused: (reasons: readonly string[], missing: readonly string[]) =>
+ `${reasons.length > 0 ? `${reasons.join("; ")}. ` : ""}` +
+ `Not installed yet: ${missing.join(", ")}. Install again to retry.`,
},
theme: "Theme",
themeInfo:
diff --git a/packages/web/src/lib/strings.ts b/packages/web/src/lib/strings.ts
index 911069b0..da2526bd 100644
--- a/packages/web/src/lib/strings.ts
+++ b/packages/web/src/lib/strings.ts
@@ -869,6 +869,16 @@ export const zh = {
later: "暂不",
dontAsk: "此机器不再询问",
noProject: "请先打开一个项目:后端会安装到当前项目。",
+ /** The run stopped on a request that never answered — the reason, not a package's own. */
+ installStopped: (reason: string) => `安装请求失败:${reason}`,
+ /**
+ * What the prompt keeps after a run that left packages behind: the reasons it has (a package
+ * that would not load, a request that failed), then the ones still missing — they are what
+ * the Install button behind this sentence retries.
+ */
+ installRefused: (reasons: readonly string[], missing: readonly string[]) =>
+ `${reasons.length > 0 ? `${reasons.join(";")}。` : ""}` +
+ `还没装上:${missing.join("、")}。可以再点一次「安装」。`,
},
theme: "主题",
themeInfo: "应用的整体风格:布局、线条、字体与动效随之改变,内容与其他设置不受影响。",
diff --git a/packages/web/test/sandbox-backend-refusal.test.ts b/packages/web/test/sandbox-backend-refusal.test.ts
new file mode 100644
index 00000000..81703303
--- /dev/null
+++ b/packages/web/test/sandbox-backend-refusal.test.ts
@@ -0,0 +1,93 @@
+/**
+ * The install prompt on the Sandbox card (src/features/settings/sandbox-backend-refusal.ts): the
+ * sentence it keeps when a run of backend packages did not leave the machine with what the switch
+ * needs.
+ *
+ * What the test pins is what a reader needs after a refusal: whose words the reason is in, and
+ * which packages are named. A package that installed but failed to load is quoted with the
+ * server's own words; a request that never answered is read through `refusalText` (7.19), so the
+ * code's localized sentence is used rather than the wire's English. Only what is still missing is
+ * listed — those are what the button behind the sentence retries, and installing again what
+ * already landed reloads the server's plugins for nothing.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { ApiError } from "../src/api/client";
+import { en as EN } from "../src/lib/strings-en";
+import { S, setActiveStrings, zh as ZH } from "../src/lib/strings";
+import { backendInstallRefusal } from "../src/features/settings/sandbox-backend-refusal";
+
+const BW = "@adelie/sandbox-bwrap";
+const DSH = "@adelie/sandbox-dsh";
+
+afterEach(() => {
+ setActiveStrings(ZH);
+});
+
+describe("backendInstallRefusal", () => {
+ it("says nothing when every offered package installed", () => {
+ expect(backendInstallRefusal([], null, [])).toBeNull();
+ });
+
+ it("quotes a package that installed but failed to load, in the server's own words", () => {
+ const line = backendInstallRefusal([{ pkg: BW, error: "no such module: bwrap" }], null, [BW]);
+ expect(line).toContain(S.plugins.deploymentFailedToast(BW, "no such module: bwrap"));
+ // The reason is the package's, not a request's — nothing claims the request failed.
+ expect(line).not.toContain(S.settings.sandboxBackendPrompt.installStopped(""));
+ });
+
+ it("reads a request that never answered through its code's localized sentence", () => {
+ const refused = new ApiError(500, "internal", "RAW ENGLISH SERVER MESSAGE");
+ const line = backendInstallRefusal([], { error: refused }, [BW]);
+ expect(line).toContain(S.errors.byCode["internal"] as string);
+ expect(line).not.toContain("RAW ENGLISH");
+ });
+
+ it("names only the packages still missing — what the button retries", () => {
+ // The first package landed, the run stopped on the second: only the second is left.
+ const line = backendInstallRefusal([], { error: new ApiError(500, "internal", "boom") }, [DSH]);
+ expect(line).toContain(DSH);
+ expect(line).not.toContain(BW);
+ });
+
+ it("does not double the full stop a reason already ends with", () => {
+ const line = backendInstallRefusal([], { error: new ApiError(500, "internal", "boom") }, [BW]);
+ expect(line).toBe(
+ `${S.settings.sandboxBackendPrompt.installStopped(
+ S.errors.byCode["internal"] as string,
+ )}还没装上:${BW}。可以再点一次「安装」。`,
+ );
+ expect(line).not.toContain("。。");
+ });
+
+ it("keeps every reason when a package failed to load and a later request threw", () => {
+ const line = backendInstallRefusal(
+ [{ pkg: BW, error: "refused by the kernel" }],
+ { error: new ApiError(502, "internal", "boom") },
+ [BW, DSH],
+ );
+ expect(line).toContain(S.plugins.deploymentFailedToast(BW, "refused by the kernel"));
+ expect(line).toContain(S.settings.sandboxBackendPrompt.installStopped(""));
+ expect(line).toContain("还没装上");
+ expect(line?.endsWith(S.settings.sandboxBackendPrompt.installRefused([], [BW, DSH]))).toBe(
+ true,
+ );
+ });
+
+ it("shows a value this codebase raised as it wrote it", () => {
+ const line = backendInstallRefusal([], { error: new Error("the prompt has no Project") }, [BW]);
+ expect(line).toContain("the prompt has no Project");
+ expect(line).not.toContain(S.common.unknownError);
+ });
+
+ it("speaks the active language", () => {
+ setActiveStrings(EN);
+ const line = backendInstallRefusal([{ pkg: BW, error: "boom" }], null, [BW]);
+ expect(line).toBe(
+ EN.settings.sandboxBackendPrompt.installRefused(
+ [EN.plugins.deploymentFailedToast(BW, "boom")],
+ [BW],
+ ),
+ );
+ expect(line).toContain("Not installed yet");
+ });
+});