Skip to content

Your lightweight open-source personal agent.

fix(webui): make pairing recovery explicit and retryable

Xubin Renb89ef23df5ac
diff --git a/docs/guides/feishu-ai-agent.md b/docs/guides/feishu-ai-agent.md
index cff436a0c..9c4458dc6 100644
--- a/docs/guides/feishu-ai-agent.md
+++ b/docs/guides/feishu-ai-agent.md
@@ -100,6 +100,7 @@ After approval, DM the bot again or mention it in a group chat:
- If streaming cards fail, confirm `cardkit:card:write` or set `"streaming": false`.
- If no messages arrive, check Feishu/Lark event permissions, Long Connection mode, and `nanobot gateway --verbose`.
- If a first DM returns a pairing code, approve it before testing normal replies.
+- If WebUI cannot approve a pending code, check the reported error and select **Retry**. You do not need another code while the current one is valid.
- If WebUI reports that the pairing code could not be sent, the DM reached nanobot but its reply failed. Check the gateway log for the Feishu error and request ID, check that the app has permission to send messages as a bot (`im:message:send_as_bot`), and publish any permission changes. Then send another private message to retry; nanobot reuses the unexpired code. Pairing replies use plain text and do not need streaming-card permissions.
- If neither a code nor a pairing request appears, check the running gateway, the app's receive-message subscription, and which assistant you messaged. A saved App ID and App Secret mean **Configured**, not that message delivery has been tested. Do not set `allowFrom` to `*` to work around pairing failures.
diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 1fca7e360..d5613338d 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -617,10 +617,11 @@ function PairingCodePopup({
busyCode: string | null;
error: string | null;
onApprove: (code: string) => void;
- onDismiss: (code: string) => void;
+ onDismiss: (request: PairingRequestInfo) => void;
}) {
const { t } = useTranslation();
const [value, setValue] = useState("");
+ const attemptedCode = useRef<string | null>(null);
const normalizedCode = normalizePairingCode(value);
const matchedRequest = useMemo(
() => requests.find((request) => request.code === normalizedCode) ?? null,
@@ -638,12 +639,16 @@ function PairingCodePopup({
const showNoMatch = isCompleteCode && !matchedRequest && !busyCode;
useEffect(() => {
- if (!matchedRequest || busyCode) return;
+ if (!matchedRequest || busyCode || attemptedCode.current === matchedRequest.code) return;
+ attemptedCode.current = matchedRequest.code;
onApprove(matchedRequest.code);
}, [busyCode, matchedRequest, onApprove]);
useEffect(() => {
- if (!requests.length) setValue("");
+ if (!requests.length) {
+ setValue("");
+ attemptedCode.current = null;
+ }
}, [requests.length]);
if (!firstRequest) return null;
@@ -655,7 +660,10 @@ function PairingCodePopup({
matched={Boolean(matchedRequest)}
invalid={showNoMatch}
ariaLabel={t("app.pairing.code", { defaultValue: "Pairing code" })}
- onChange={(next) => setValue(formatPairingCodeInput(next))}
+ onChange={(next) => {
+ attemptedCode.current = null;
+ setValue(formatPairingCodeInput(next));
+ }}
/>
);
@@ -696,7 +704,7 @@ function PairingCodePopup({
<button
type="button"
aria-label={t("common.close", { defaultValue: "Close" })}
- onClick={() => onDismiss(displayRequest.code)}
+ onClick={() => onDismiss(displayRequest)}
className="rounded-full p-1 text-muted-foreground transition hover:bg-muted hover:text-foreground"
>
<X className="h-4 w-4" aria-hidden />
@@ -722,7 +730,7 @@ function PairingCodePopup({
{!deliveryBlocked || total > 1 ? (
<div className="mt-3 flex items-center justify-between gap-3 text-[12.5px] text-muted-foreground">
<span>
- {matchedRequest
+ {matchedRequest && busyCode === matchedRequest.code
? t("app.pairing.matched", {
defaultValue: "Matched {{channel}}. Connecting...",
channel: channelLabel(matchedRequest.channel),
@@ -752,7 +760,19 @@ function PairingCodePopup({
) : null}
{error ? (
- <p className="mt-2 text-[12px] leading-5 text-destructive">{error}</p>
+ <div className="mt-2 space-y-2">
+ <p role="alert" className="text-[12px] leading-5 text-destructive">{error}</p>
+ {matchedRequest ? (
+ <Button
+ variant="outline"
+ size="sm"
+ disabled={Boolean(busyCode)}
+ onClick={() => onApprove(matchedRequest.code)}
+ >
+ {t("common.retry", { defaultValue: "Retry" })}
+ </Button>
+ ) : null}
+ </div>
) : null}
</div>
</div>
@@ -1256,7 +1276,10 @@ function Shell({
const [pairingBusyCode, setPairingBusyCode] = useState<string | null>(null);
const [pairingError, setPairingError] = useState<string | null>(null);
const pairingRefreshRef = useRef<Promise<number> | null>(null);
- const [snoozedPairingCodes, setSnoozedPairingCodes] = useState<Map<string, number>>(
+ const [snoozedPairingCodes, setSnoozedPairingCodes] = useState<Map<string, {
+ until: number;
+ deliveryStatus: PairingRequestInfo["delivery_status"];
+ }>>(
() => new Map(),
);
const [runningChatIds, setRunningChatIds] = useState<Set<string>>(() => new Set());
@@ -1451,11 +1474,13 @@ function Shell({
setPairingRequests(requests);
setSnoozedPairingCodes((current) => {
if (current.size === 0) return current;
- const activeCodes = new Set(requests.map((request) => request.code));
+ const activeRequests = new Map(requests.map((request) => [request.code, request]));
const now = Date.now();
const next = new Map(
Array.from(current).filter(
- ([code, snoozedUntil]) => activeCodes.has(code) && snoozedUntil > now,
+ ([code, snooze]) => activeRequests.has(code)
+ && snooze.until > now
+ && activeRequests.get(code)?.delivery_status === snooze.deliveryStatus,
),
);
return next.size === current.size ? current : next;
@@ -2456,8 +2481,8 @@ function Shell({
() => {
const now = Date.now();
return pairingRequests.filter((request) => {
- const snoozedUntil = snoozedPairingCodes.get(request.code);
- return !snoozedUntil || snoozedUntil <= now;
+ const snooze = snoozedPairingCodes.get(request.code);
+ return !snooze || snooze.until <= now;
});
},
[pairingRequests, snoozedPairingCodes],
@@ -2486,12 +2511,13 @@ function Shell({
[client, refreshPairingRequests],
);
- const onDismissPairingRequest = useCallback((code: string) => {
+ const onDismissPairingRequest = useCallback((request: PairingRequestInfo) => {
setSnoozedPairingCodes((current) => {
- const snoozedUntil = Date.now() + PAIRING_DISMISS_SNOOZE_MS;
- if (current.get(code) === snoozedUntil) return current;
const next = new Map(current);
- next.set(code, snoozedUntil);
+ next.set(request.code, {
+ until: Date.now() + PAIRING_DISMISS_SNOOZE_MS,
+ deliveryStatus: request.delivery_status,
+ });
return next;
});
}, []);
diff --git a/webui/src/i18n/locales/en/common.json b/webui/src/i18n/locales/en/common.json
index 25bf12175..690d01f44 100644
--- a/webui/src/i18n/locales/en/common.json
+++ b/webui/src/i18n/locales/en/common.json
@@ -2478,6 +2478,7 @@
}
},
"common": {
+ "retry": "Retry",
"dismiss": "Dismiss",
"close": "Close",
"current": "Current",
diff --git a/webui/src/i18n/locales/es/common.json b/webui/src/i18n/locales/es/common.json
index 4647d0c91..c74f675a3 100644
--- a/webui/src/i18n/locales/es/common.json
+++ b/webui/src/i18n/locales/es/common.json
@@ -2279,6 +2279,7 @@
}
},
"common": {
+ "retry": "Reintentar",
"dismiss": "Cerrar",
"close": "Cerrar",
"current": "Actual",
diff --git a/webui/src/i18n/locales/fr/common.json b/webui/src/i18n/locales/fr/common.json
index f90ba9de3..4e93deb42 100644
--- a/webui/src/i18n/locales/fr/common.json
+++ b/webui/src/i18n/locales/fr/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "Réessayer",
"dismiss": "Fermer",
"close": "Fermer",
"current": "Actuel",
diff --git a/webui/src/i18n/locales/id/common.json b/webui/src/i18n/locales/id/common.json
index 584691a14..b73b4413b 100644
--- a/webui/src/i18n/locales/id/common.json
+++ b/webui/src/i18n/locales/id/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "Coba lagi",
"dismiss": "Tutup",
"close": "Tutup",
"current": "Saat ini",
diff --git a/webui/src/i18n/locales/ja/common.json b/webui/src/i18n/locales/ja/common.json
index 6dfdab551..c3c809ac8 100644
--- a/webui/src/i18n/locales/ja/common.json
+++ b/webui/src/i18n/locales/ja/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "再試行",
"dismiss": "閉じる",
"close": "閉じる",
"current": "現在",
diff --git a/webui/src/i18n/locales/ko/common.json b/webui/src/i18n/locales/ko/common.json
index 48009cc5e..73e31b2e9 100644
--- a/webui/src/i18n/locales/ko/common.json
+++ b/webui/src/i18n/locales/ko/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "다시 시도",
"dismiss": "닫기",
"close": "닫기",
"current": "현재",
diff --git a/webui/src/i18n/locales/pt-BR/common.json b/webui/src/i18n/locales/pt-BR/common.json
index 0b5c4cfc1..16c7f9096 100644
--- a/webui/src/i18n/locales/pt-BR/common.json
+++ b/webui/src/i18n/locales/pt-BR/common.json
@@ -2292,6 +2292,7 @@
}
},
"common": {
+ "retry": "Tentar novamente",
"dismiss": "Descartar",
"close": "Fechar",
"current": "Atual",
diff --git a/webui/src/i18n/locales/vi/common.json b/webui/src/i18n/locales/vi/common.json
index 05786fed3..9dc82aad3 100644
--- a/webui/src/i18n/locales/vi/common.json
+++ b/webui/src/i18n/locales/vi/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "Thử lại",
"dismiss": "Đóng",
"close": "Đóng",
"current": "Hiện tại",
diff --git a/webui/src/i18n/locales/zh-CN/common.json b/webui/src/i18n/locales/zh-CN/common.json
index 797f71d3c..b2804bbaf 100644
--- a/webui/src/i18n/locales/zh-CN/common.json
+++ b/webui/src/i18n/locales/zh-CN/common.json
@@ -2478,6 +2478,7 @@
}
},
"common": {
+ "retry": "重试",
"dismiss": "关闭",
"close": "关闭",
"current": "当前",
diff --git a/webui/src/i18n/locales/zh-TW/common.json b/webui/src/i18n/locales/zh-TW/common.json
index d89968463..8ba5564ae 100644
--- a/webui/src/i18n/locales/zh-TW/common.json
+++ b/webui/src/i18n/locales/zh-TW/common.json
@@ -2278,6 +2278,7 @@
}
},
"common": {
+ "retry": "重試",
"dismiss": "關閉",
"close": "關閉",
"current": "目前",
diff --git a/webui/src/tests/app-layout.test.tsx b/webui/src/tests/app-layout.test.tsx
index e5472490f..084080b14 100644
--- a/webui/src/tests/app-layout.test.tsx
+++ b/webui/src/tests/app-layout.test.tsx
@@ -4089,6 +4089,56 @@ describe("App layout", () => {
expect(within(popup).getByText("2 pending")).toBeVisible();
});
+ it("shows a recovered pairing reply even after its failure notice was dismissed", async () => {
+ vi.useFakeTimers();
+ let delivery_status = "failed";
+ mockFetchRoutes({ "/api/settings/pairing": () => ({ requests: [{
+ code: "ABCD-EFGH", channel: "feishu", sender_id: "alice", delivery_status,
+ }] }) });
+ render(<App />);
+ await act(async () => {});
+ fireEvent.click(within(screen.getByRole("dialog", { name: "Pair account" }))
+ .getByRole("button", { name: "Close" }));
+ expect(screen.queryByRole("dialog", { name: "Pair account" })).not.toBeInTheDocument();
+ await act(async () => { await vi.advanceTimersByTimeAsync(3_000); });
+ expect(screen.queryByRole("dialog", { name: "Pair account" })).not.toBeInTheDocument();
+
+ delivery_status = "sent";
+ await act(async () => { await vi.advanceTimersByTimeAsync(3_000); });
+ const popup = screen.getByRole("dialog", { name: "Pair account" });
+ expect(within(popup).getByRole("textbox", { name: "Pairing code" })).toBeEnabled();
+ expect(within(popup).queryByRole("alert")).not.toBeInTheDocument();
+ expect(requestMutationSpy).not.toHaveBeenCalled();
+ });
+
+ it("keeps a failed pairing approval idle until the user retries", async () => {
+ vi.useFakeTimers();
+ let requests = [{ code: "ABCD-EFGH", channel: "feishu", sender_id: "alice", delivery_status: "sent" }];
+ mockFetchRoutes({ "/api/settings/pairing": () => ({ requests }) });
+ requestMutationSpy
+ .mockRejectedValueOnce(new Error("Approval unavailable"))
+ // Bound the old automatic retry loop while reproducing it.
+ .mockImplementation(() => new Promise(() => {}));
+ render(<App />);
+ await act(async () => {});
+ const popup = screen.getByRole("dialog", { name: "Pair account" });
+ fireEvent.change(within(popup).getByRole("textbox", { name: "Pairing code" }), {
+ target: { value: "ABCD-EFGH" },
+ });
+ await act(async () => {});
+ await act(async () => { await vi.advanceTimersByTimeAsync(3_000); });
+ expect(requestMutationSpy).toHaveBeenCalledTimes(1);
+ expect(within(popup).getByText("Approval unavailable")).toBeVisible();
+ expect(within(popup).getByRole("textbox", { name: "Pairing code" })).toBeEnabled();
+
+ requests = [];
+ requestMutationSpy.mockResolvedValueOnce({ requests });
+ fireEvent.click(within(popup).getByRole("button", { name: "Retry" }));
+ await act(async () => {});
+ expect(requestMutationSpy).toHaveBeenCalledTimes(2);
+ expect(screen.queryByRole("dialog", { name: "Pair account" })).not.toBeInTheDocument();
+ });
+
it("reuses an in-flight pairing poll when the page becomes visible again", async () => {
let resolvePairing!: (response: Response) => void;
const pendingPairing = new Promise<Response>((resolve) => {