Skip to content

🙌 OpenHands: AI-Driven Development

feat: add Agent Canvas update-availability card to settings (#1898)

Hiep Le5f77656b769c
diff --git a/scripts/check-translation-completeness.cjs b/scripts/check-translation-completeness.cjs
index dca0170d56..09d5d82bd9 100755
--- a/scripts/check-translation-completeness.cjs
+++ b/scripts/check-translation-completeness.cjs
@@ -34,6 +34,7 @@ const IDENTICAL_VALUE_ALLOWLIST = new Set([
'SCHEMA$VERIFICATION$SECURITY_ANALYZER$CHOICE$LLM',
'SETTINGS$AGENT_SERVER_URL_PLACEHOLDER',
'SETTINGS$AGENT_TYPE_OPENHANDS',
+ 'SETTINGS$APP_UPDATE_CARD_TITLE',
'SETTINGS$AZURE_DEVOPS',
'SETTINGS$CLOUD_SETTINGS_LINK',
'SETTINGS$GITHUB',
diff --git a/src/api/agent-canvas-updates.test.ts b/src/api/agent-canvas-updates.test.ts
new file mode 100644
index 0000000000..62dfbb76dd
--- /dev/null
+++ b/src/api/agent-canvas-updates.test.ts
@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { fetchLatestAgentCanvasVersion } from "./agent-canvas-updates";
+
+function stubFetchResponse(response: Partial<Response>) {
+ const fetchMock = vi.fn().mockResolvedValue(response as Response);
+ vi.stubGlobal("fetch", fetchMock);
+ return fetchMock;
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+});
+
+describe("fetchLatestAgentCanvasVersion", () => {
+ it("fetches the npm registry latest dist-tag and returns the trimmed version", async () => {
+ const fetchMock = stubFetchResponse({
+ ok: true,
+ json: async () => ({ version: " 1.6.0 " }),
+ });
+
+ await expect(fetchLatestAgentCanvasVersion()).resolves.toBe("1.6.0");
+ expect(fetchMock).toHaveBeenCalledWith(
+ "https://registry.npmjs.org/@openhands/agent-canvas/latest",
+ expect.objectContaining({ headers: { Accept: "application/json" } }),
+ );
+ });
+
+ it("rejects when the registry responds with an error status", async () => {
+ stubFetchResponse({ ok: false, status: 503 });
+
+ await expect(fetchLatestAgentCanvasVersion()).rejects.toThrow("503");
+ });
+
+ it("rejects when the response has no usable version field", async () => {
+ stubFetchResponse({ ok: true, json: async () => ({ version: 42 }) });
+
+ await expect(fetchLatestAgentCanvasVersion()).rejects.toThrow(
+ "missing version",
+ );
+ });
+});
diff --git a/src/api/agent-canvas-updates.ts b/src/api/agent-canvas-updates.ts
new file mode 100644
index 0000000000..1db3d022eb
--- /dev/null
+++ b/src/api/agent-canvas-updates.ts
@@ -0,0 +1,37 @@
+/**
+ * Source of truth for "is a newer Agent Canvas published?".
+ *
+ * The npm registry `latest` dist-tag endpoint is CORS-open and returns the
+ * abbreviated packument for that version as JSON. Isolated here so the
+ * release channel can change (e.g. GitHub releases) without touching the
+ * query hook or the settings update card.
+ */
+const NPM_LATEST_VERSION_URL =
+ "https://registry.npmjs.org/@openhands/agent-canvas/latest";
+
+export const AGENT_CANVAS_RELEASE_NOTES_URL =
+ "https://github.com/OpenHands/agent-canvas/releases";
+
+/** Literal shell commands — intentionally not localized. */
+export const AGENT_CANVAS_UPDATE_COMMANDS = {
+ npm: "npm install -g @openhands/agent-canvas@latest",
+ docker: "docker pull ghcr.io/openhands/agent-canvas:latest",
+} as const;
+
+export async function fetchLatestAgentCanvasVersion(
+ signal?: AbortSignal,
+): Promise<string> {
+ const response = await fetch(NPM_LATEST_VERSION_URL, {
+ signal,
+ headers: { Accept: "application/json" },
+ });
+ if (!response.ok) {
+ throw new Error(`npm registry responded ${response.status}`);
+ }
+ const body: unknown = await response.json();
+ const version = (body as { version?: unknown } | null)?.version;
+ if (typeof version !== "string" || !version.trim()) {
+ throw new Error("npm registry response missing version");
+ }
+ return version.trim();
+}
diff --git a/src/api/agent-server-compatibility.ts b/src/api/agent-server-compatibility.ts
index 0962d9bd63..7aea8a8357 100644
--- a/src/api/agent-server-compatibility.ts
+++ b/src/api/agent-server-compatibility.ts
@@ -226,7 +226,7 @@ export function getCachedAgentServerVersion(
return getDisplayAgentServerVersion(cachedAgentServerInfo);
}
-function compareAgentServerVersions(actual: string, required: string) {
+export function compareAgentServerVersions(actual: string, required: string) {
const parsedActual = parseAgentServerVersion(actual);
const parsedRequired = parseAgentServerVersion(required);
diff --git a/src/components/features/settings/agent-canvas-update-card.test.tsx b/src/components/features/settings/agent-canvas-update-card.test.tsx
new file mode 100644
index 0000000000..30cd3faa25
--- /dev/null
+++ b/src/components/features/settings/agent-canvas-update-card.test.tsx
@@ -0,0 +1,154 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+ AGENT_CANVAS_RELEASE_NOTES_URL,
+ AGENT_CANVAS_UPDATE_COMMANDS,
+} from "#/api/agent-canvas-updates";
+import { AGENT_CANVAS_CLIENT_VERSION } from "#/api/client-source";
+import { AgentCanvasUpdateCard } from "./agent-canvas-update-card";
+
+const { fetchLatestVersionMock, getLockedCloudHostMock } = vi.hoisted(() => ({
+ fetchLatestVersionMock: vi.fn(),
+ getLockedCloudHostMock: vi.fn(),
+}));
+
+vi.mock("#/api/agent-canvas-updates", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("#/api/agent-canvas-updates")>()),
+ fetchLatestAgentCanvasVersion: fetchLatestVersionMock,
+}));
+
+vi.mock("#/api/agent-server-config", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("#/api/agent-server-config")>()),
+ getLockedCloudHost: getLockedCloudHostMock,
+}));
+
+function renderCard() {
+ const queryClient = new QueryClient();
+ return render(
+ <QueryClientProvider client={queryClient}>
+ <AgentCanvasUpdateCard />
+ </QueryClientProvider>,
+ );
+}
+
+beforeEach(() => {
+ getLockedCloudHostMock.mockReturnValue(null);
+});
+
+afterEach(() => {
+ vi.clearAllMocks();
+});
+
+describe("AgentCanvasUpdateCard", () => {
+ it("shows the running version and an up-to-date badge when the registry matches it", async () => {
+ fetchLatestVersionMock.mockResolvedValue(AGENT_CANVAS_CLIENT_VERSION);
+
+ renderCard();
+
+ expect(screen.getByText(AGENT_CANVAS_CLIENT_VERSION)).toBeInTheDocument();
+ expect(
+ await screen.findByTestId("agent-canvas-update-badge"),
+ ).toHaveTextContent("SETTINGS$APP_UPDATE_BADGE_UP_TO_DATE");
+ });
+
+ it("flags an available update when the registry reports a newer version", async () => {
+ fetchLatestVersionMock.mockResolvedValue("999.0.0");
+
+ renderCard();
+ expect(
+ await screen.findByTestId("agent-canvas-update-badge"),
+ ).toHaveTextContent("SETTINGS$APP_UPDATE_BADGE_UPDATE_AVAILABLE");
+ fireEvent.click(screen.getByTestId("agent-canvas-update-toggle"));
+
+ expect(screen.getByTestId("agent-canvas-update-status")).toHaveTextContent(
+ "SETTINGS$APP_UPDATE_AVAILABLE_MESSAGE",
+ );
+ });
+
+ it("treats a running version newer than the registry as up to date", async () => {
+ fetchLatestVersionMock.mockResolvedValue("0.0.1");
+
+ renderCard();
+
+ expect(
+ await screen.findByTestId("agent-canvas-update-badge"),
+ ).toHaveTextContent("SETTINGS$APP_UPDATE_BADGE_UP_TO_DATE");
+ });
+
+ it("shows no badge and a quiet inline message when the check fails", async () => {
+ fetchLatestVersionMock.mockRejectedValue(new Error("offline"));
+
+ renderCard();
+ fireEvent.click(screen.getByTestId("agent-canvas-update-toggle"));
+
+ expect(
+ await screen.findByText("SETTINGS$APP_UPDATE_CHECK_FAILED"),
+ ).toBeInTheDocument();
+ expect(
+ screen.queryByTestId("agent-canvas-update-badge"),
+ ).not.toBeInTheDocument();
+ });
+
+ it("keeps update instructions collapsed until the header is toggled", async () => {
+ fetchLatestVersionMock.mockResolvedValue(AGENT_CANVAS_CLIENT_VERSION);
+
+ renderCard();
+ expect(
+ screen.queryByTestId("agent-canvas-update-command-npm"),
+ ).not.toBeInTheDocument();
+ fireEvent.click(screen.getByTestId("agent-canvas-update-toggle"));
+
+ expect(
+ screen.getByTestId("agent-canvas-update-command-npm"),
+ ).toHaveTextContent(AGENT_CANVAS_UPDATE_COMMANDS.npm);
+ expect(
+ screen.getByTestId("agent-canvas-update-command-docker"),
+ ).toHaveTextContent(AGENT_CANVAS_UPDATE_COMMANDS.docker);
+ expect(
+ screen.getByTestId("agent-canvas-update-release-notes"),
+ ).toHaveAttribute("href", AGENT_CANVAS_RELEASE_NOTES_URL);
+ });
+
+ it("re-checks the registry when Check for updates is clicked", async () => {
+ fetchLatestVersionMock.mockResolvedValue(AGENT_CANVAS_CLIENT_VERSION);
+
+ renderCard();
+ await screen.findByTestId("agent-canvas-update-badge");
+ expect(fetchLatestVersionMock).toHaveBeenCalledTimes(1);
+ fireEvent.click(screen.getByTestId("agent-canvas-update-toggle"));
+ fireEvent.click(screen.getByTestId("agent-canvas-update-check-button"));
+
+ await waitFor(() =>
+ expect(fetchLatestVersionMock).toHaveBeenCalledTimes(2),
+ );
+ });
+
+ it("copies the update command to the clipboard", async () => {
+ const writeText = vi.fn().mockResolvedValue(undefined);
+ Object.defineProperty(window.navigator, "clipboard", {
+ value: { writeText },
+ configurable: true,
+ });
+ fetchLatestVersionMock.mockResolvedValue(AGENT_CANVAS_CLIENT_VERSION);
+
+ renderCard();
+ fireEvent.click(screen.getByTestId("agent-canvas-update-toggle"));
+ // First copy button belongs to the npm command row.
+ fireEvent.click(screen.getAllByTestId("copy-to-clipboard")[0]);
+
+ expect(writeText).toHaveBeenCalledWith(AGENT_CANVAS_UPDATE_COMMANDS.npm);
+ });
+
+ it("renders nothing and skips the check when locked to a cloud deployment", () => {
+ getLockedCloudHostMock.mockReturnValue("https://app.openhands.dev");
+ fetchLatestVersionMock.mockResolvedValue(AGENT_CANVAS_CLIENT_VERSION);
+
+ renderCard();
+
+ expect(
+ screen.queryByTestId("agent-canvas-update-card"),
+ ).not.toBeInTheDocument();
+ expect(fetchLatestVersionMock).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/components/features/settings/agent-canvas-update-card.tsx b/src/components/features/settings/agent-canvas-update-card.tsx
new file mode 100644
index 0000000000..6b377126dc
--- /dev/null
+++ b/src/components/features/settings/agent-canvas-update-card.tsx
@@ -0,0 +1,226 @@
+import { useId, useState } from "react";
+import { useTranslation } from "react-i18next";
+import {
+ ChevronDown,
+ ChevronUp,
+ CircleCheck,
+ ExternalLink,
+ Info,
+ RefreshCw,
+} from "lucide-react";
+import {
+ AGENT_CANVAS_RELEASE_NOTES_URL,
+ AGENT_CANVAS_UPDATE_COMMANDS,
+} from "#/api/agent-canvas-updates";
+import { compareAgentServerVersions } from "#/api/agent-server-compatibility";
+import { getLockedCloudHost } from "#/api/agent-server-config";
+import { AGENT_CANVAS_CLIENT_VERSION } from "#/api/client-source";
+import { BrandButton } from "#/components/features/settings/brand-button";
+import { CopyToClipboardButton } from "#/components/shared/buttons/copy-to-clipboard-button";
+import { useLatestAgentCanvasVersion } from "#/hooks/query/use-latest-agent-canvas-version";
+import { I18nKey } from "#/i18n/declaration";
+import { cn } from "#/utils/utils";
+
+function UpdateCommandRow({
+ command,
+ testId,
+}: {
+ command: string;
+ testId: string;
+}) {
+ const [copied, setCopied] = useState(false);
+
+ const handleCopy = () => {
+ navigator.clipboard.writeText(command);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ };
+
+ return (
+ <div className="flex items-center gap-2 rounded-lg bg-[var(--oh-surface-deep)] px-2 py-1.5">
+ <code
+ data-testid={testId}
+ className="min-w-0 flex-1 select-all break-all font-mono text-[11px] leading-4 text-white"
+ >
+ {command}
+ </code>
+ <CopyToClipboardButton
+ isHidden={false}
+ isDisabled={false}
+ onClick={handleCopy}
+ mode={copied ? "copied" : "copy"}
+ />
+ </div>
+ );
+}
+
+/**
+ * Information-only version/update card for the settings navigation surfaces.
+ * Never blocks or toasts; check failures degrade to a quiet inline message.
+ * Hidden in locked-to-Cloud deployments — the hosted canvas has no npm/docker
+ * install to update.
+ */
+export function AgentCanvasUpdateCard() {
+ const { t } = useTranslation("openhands");
+ const [expanded, setExpanded] = useState(false);
+ // The card is mounted on multiple settings surfaces at once; ids must not
+ // collide across instances.
+ const detailsId = useId();
+ const isLockedToCloud = getLockedCloudHost() !== null;
+ const latestVersionQuery = useLatestAgentCanvasVersion({
+ enabled: !isLockedToCloud,
+ });
+
+ if (isLockedToCloud) return null;
+
+ const latestVersion = latestVersionQuery.data;
+ const comparison =
+ latestVersion !== undefined
+ ? compareAgentServerVersions(latestVersion, AGENT_CANVAS_CLIENT_VERSION)
+ : null;
+ const updateAvailable = comparison === 1;
+ // 0 or -1: running the npm latest or newer (local dev build).
+ const upToDate = comparison !== null && comparison <= 0;
+ const ChevronIcon = expanded ? ChevronUp : ChevronDown;
+
+ return (
+ <section
+ data-testid="agent-canvas-update-card"
+ className="flex flex-col gap-2 rounded-xl border border-[var(--oh-border)] bg-[var(--oh-surface-raised)] p-3"
+ >
+ <button
+ type="button"
+ onClick={() => setExpanded((prev) => !prev)}
+ aria-expanded={expanded}
+ aria-controls={detailsId}
+ data-testid="agent-canvas-update-toggle"
+ className="flex w-full cursor-pointer items-center gap-2 text-left"
+ >
+ <span className="flex-1 truncate text-xs font-medium text-white">
+ {t(I18nKey.SETTINGS$APP_UPDATE_CARD_TITLE)}
+ </span>
+ {comparison !== null && (
+ <span
+ data-testid="agent-canvas-update-badge"
+ className={cn(
+ "inline-flex shrink-0 items-center rounded-full border border-[var(--oh-border)] bg-[var(--oh-surface)] px-1.5 py-0.5 text-[10px] font-medium leading-none",
+ updateAvailable ? "text-warning" : "text-success",
+ )}
+ >
+ {t(
+ updateAvailable
+ ? I18nKey.SETTINGS$APP_UPDATE_BADGE_UPDATE_AVAILABLE
+ : I18nKey.SETTINGS$APP_UPDATE_BADGE_UP_TO_DATE,
+ )}
+ </span>
+ )}
+ <ChevronIcon
+ className="size-4 shrink-0 text-[var(--oh-muted)]"
+ aria-hidden
+ />
+ </button>
+
+ <div className="flex items-center justify-between text-xs">
+ <span className="text-[var(--oh-text-dim)]">
+ {t(I18nKey.SETTINGS$APP_UPDATE_VERSION_LABEL)}
+ </span>
+ <span className="font-mono text-white">
+ {AGENT_CANVAS_CLIENT_VERSION}
+ </span>
+ </div>
+
+ {expanded && (
+ <div id={detailsId} className="flex flex-col gap-3 pt-1">
+ <div
+ data-testid="agent-canvas-update-status"
+ className="flex items-start gap-2 text-xs"
+ >
+ {latestVersionQuery.isPending ? (
+ <span className="text-[var(--oh-muted)]">
+ {t(I18nKey.SETTINGS$APP_UPDATE_CHECKING)}
+ </span>
+ ) : updateAvailable ? (
+ <>
+ <Info className="size-4 shrink-0 text-warning" aria-hidden />
+ <span className="text-warning">
+ {t(I18nKey.SETTINGS$APP_UPDATE_AVAILABLE_MESSAGE, {
+ version: latestVersion,
+ })}
+ </span>
+ </>
+ ) : upToDate ? (
+ <>
+ <CircleCheck
+ className="size-4 shrink-0 text-success"
+ aria-hidden
+ />
+ <span className="text-success">
+ {t(I18nKey.SETTINGS$APP_UPDATE_LATEST_MESSAGE)}
+ </span>
+ </>
+ ) : (
+ <span className="text-[var(--oh-muted)]">
+ {t(I18nKey.SETTINGS$APP_UPDATE_CHECK_FAILED)}
+ </span>
+ )}
+ </div>
+
+ <BrandButton
+ testId="agent-canvas-update-check-button"
+ type="button"
+ variant="secondary"
+ className="w-full"
+ isDisabled={latestVersionQuery.isFetching}
+ aria-busy={latestVersionQuery.isFetching}
+ onClick={() => latestVersionQuery.refetch()}
+ startContent={
+ <RefreshCw
+ className={cn(
+ "size-4",
+ latestVersionQuery.isFetching && "animate-spin",
+ )}
+ aria-hidden
+ />
+ }
+ >
+ {t(I18nKey.SETTINGS$APP_UPDATE_CHECK_BUTTON)}
+ </BrandButton>
+
+ <div className="flex flex-col gap-2 rounded-lg border border-[var(--oh-border-subtle)] p-3 text-xs">
+ <div className="flex items-center gap-1.5 text-white">
+ <Info className="size-4 shrink-0" aria-hidden />
+ <span className="font-medium">
+ {t(I18nKey.SETTINGS$APP_UPDATE_HOW_TO_UPDATE)}
+ </span>
+ </div>
+ <span className="text-[var(--oh-text-dim)]">
+ {t(I18nKey.SETTINGS$APP_UPDATE_RUN_COMMANDS)}
+ </span>
+ <UpdateCommandRow
+ command={AGENT_CANVAS_UPDATE_COMMANDS.npm}
+ testId="agent-canvas-update-command-npm"
+ />
+ <span className="text-center text-[var(--oh-text-dim)]">
+ {t(I18nKey.SETTINGS$APP_UPDATE_OR)}
+ </span>
+ <UpdateCommandRow
+ command={AGENT_CANVAS_UPDATE_COMMANDS.docker}
+ testId="agent-canvas-update-command-docker"
+ />
+ </div>
+
+ <a
+ data-testid="agent-canvas-update-release-notes"
+ href={AGENT_CANVAS_RELEASE_NOTES_URL}
+ target="_blank"
+ rel="noopener noreferrer"
+ className="inline-flex items-center gap-1 self-start text-xs text-[var(--oh-accent)] underline"
+ >
+ {t(I18nKey.SETTINGS$APP_UPDATE_RELEASE_NOTES)}
+ <ExternalLink size={12} aria-hidden />
+ </a>
+ </div>
+ )}
+ </section>
+ );
+}
diff --git a/src/components/features/settings/settings-desktop-sidebar.tsx b/src/components/features/settings/settings-desktop-sidebar.tsx
index c8d06b826d..5d36353561 100644
--- a/src/components/features/settings/settings-desktop-sidebar.tsx
+++ b/src/components/features/settings/settings-desktop-sidebar.tsx
@@ -4,6 +4,7 @@ import { Typography } from "#/ui/typography";
import { I18nKey } from "#/i18n/declaration";
import { SettingsNavRenderedItem } from "#/hooks/use-settings-nav-items";
import { SidebarNavLink } from "#/components/features/sidebar/sidebar-nav-link";
+import { AgentCanvasUpdateCard } from "#/components/features/settings/agent-canvas-update-card";
import { BackendSyncedSettingsBadge } from "#/components/features/settings/backend-synced-settings-badge";
import { CloudSettingsLink } from "#/components/features/settings/cloud-settings-link";
import { IntegrationsSettingsLink } from "#/components/features/settings/integrations-settings-link";
@@ -66,6 +67,9 @@ export function SettingsDesktopSidebar({
<IntegrationsSettingsLink />
<CloudSettingsLink />
</div>
+ <div className="px-2 pt-3">
+ <AgentCanvasUpdateCard />
+ </div>
<div className="px-2 pt-3">
<BackendSyncedSettingsBadge />
</div>
diff --git a/src/components/features/settings/settings-mobile-drawer.tsx b/src/components/features/settings/settings-mobile-drawer.tsx
index a6151a3178..ad0e648801 100644
--- a/src/components/features/settings/settings-mobile-drawer.tsx
+++ b/src/components/features/settings/settings-mobile-drawer.tsx
@@ -9,6 +9,7 @@ import { SettingsNavHeader } from "./settings-nav-header";
import { SettingsNavDivider } from "./settings-nav-divider";
import { SettingsNavLink } from "./settings-nav-link";
import { navInteractiveTransitionClassName } from "#/components/features/sidebar/sidebar-layout";
+import { AgentCanvasUpdateCard } from "#/components/features/settings/agent-canvas-update-card";
import { BackendSyncedSettingsBadge } from "#/components/features/settings/backend-synced-settings-badge";
import { CloudSettingsLink } from "#/components/features/settings/cloud-settings-link";
import { IntegrationsSettingsLink } from "#/components/features/settings/integrations-settings-link";
@@ -93,6 +94,10 @@ export function SettingsMobileDrawer({
<CloudSettingsLink />
</div>
+ <div className="px-2 pt-3">
+ <AgentCanvasUpdateCard />
+ </div>
+
<div className="px-2 pt-3">
<BackendSyncedSettingsBadge />
</div>
diff --git a/src/components/features/settings/settings-mobile-hub.tsx b/src/components/features/settings/settings-mobile-hub.tsx
index ef21c103df..5770d8b030 100644
--- a/src/components/features/settings/settings-mobile-hub.tsx
+++ b/src/components/features/settings/settings-mobile-hub.tsx
@@ -3,6 +3,7 @@ import { Typography } from "#/ui/typography";
import { I18nKey } from "#/i18n/declaration";
import { SettingsNavRenderedItem } from "#/hooks/use-settings-nav-items";
import { SidebarNavLink } from "#/components/features/sidebar/sidebar-nav-link";
+import { AgentCanvasUpdateCard } from "#/components/features/settings/agent-canvas-update-card";
import { BackendSyncedSettingsBadge } from "#/components/features/settings/backend-synced-settings-badge";
import { CloudSettingsLink } from "#/components/features/settings/cloud-settings-link";
import { IntegrationsSettingsLink } from "#/components/features/settings/integrations-settings-link";
@@ -39,6 +40,7 @@ export function SettingsMobileHub({ navigationItems }: SettingsMobileHubProps) {
<IntegrationsSettingsLink />
<CloudSettingsLink />
</nav>
+ <AgentCanvasUpdateCard />
<div className="pt-1">
<BackendSyncedSettingsBadge />
</div>
diff --git a/src/hooks/query/query-keys.ts b/src/hooks/query/query-keys.ts
index 16b4af8883..40c8a31727 100644
--- a/src/hooks/query/query-keys.ts
+++ b/src/hooks/query/query-keys.ts
@@ -56,6 +56,11 @@ export const PLUGINS_QUERY_KEYS = {
local: ["plugins-local"] as const,
} as const;
+export const APP_UPDATE_QUERY_KEYS = {
+ /** Latest published @openhands/agent-canvas version (npm `latest` dist-tag). */
+ latestVersion: ["agent-canvas-latest-version"] as const,
+} as const;
+
/** Cache configuration shared across all config-related queries */
export const CONFIG_CACHE_OPTIONS = {
staleTime: 1000 * 60 * 5, // 5 minutes
diff --git a/src/hooks/query/use-latest-agent-canvas-version.ts b/src/hooks/query/use-latest-agent-canvas-version.ts
new file mode 100644
index 0000000000..762b0361ec
--- /dev/null
+++ b/src/hooks/query/use-latest-agent-canvas-version.ts
@@ -0,0 +1,26 @@
+import { useQuery } from "@tanstack/react-query";
+import { fetchLatestAgentCanvasVersion } from "#/api/agent-canvas-updates";
+import { APP_UPDATE_QUERY_KEYS } from "./query-keys";
+
+/**
+ * Latest published Agent Canvas version (npm `latest` dist-tag).
+ *
+ * Information-only: failures must stay quiet (`meta.disableToast`) — the
+ * settings update card renders them inline. The card's "Check for updates"
+ * button is `refetch()`, which bypasses `staleTime`.
+ */
+export function useLatestAgentCanvasVersion({
+ enabled = true,
+}: { enabled?: boolean } = {}) {
+ return useQuery({
+ queryKey: APP_UPDATE_QUERY_KEYS.latestVersion,
+ queryFn: ({ signal }) => fetchLatestAgentCanvasVersion(signal),
+ enabled,
+ // Offline/air-gapped must settle into the quiet inline state immediately
+ // rather than sitting through exponential backoff.
+ retry: false,
+ refetchOnWindowFocus: false,
+ staleTime: 1000 * 60 * 60, // the settings sidebar remounts per navigation; don't hammer npm
+ meta: { disableToast: true },
+ });
+}
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index e2ae8fdaa3..3cca4fc12f 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -34831,5 +34831,226 @@
"de": "Kein API-Schlüssel erforderlich. Der Server übernimmt den OAuth-Fluss automatisch.",
"uk": "Ключ API не потрібен. Сервер автоматично обробляє процес OAuth.",
"ca": "No cal cap clau d'API. El servidor gestiona el flux d'OAuth automàticament."
+ },
+ "SETTINGS$APP_UPDATE_CARD_TITLE": {
+ "en": "Agent Canvas",
+ "ja": "Agent Canvas",
+ "zh-CN": "Agent Canvas",
+ "zh-TW": "Agent Canvas",
+ "ko-KR": "Agent Canvas",
+ "no": "Agent Canvas",
+ "it": "Agent Canvas",
+ "pt": "Agent Canvas",
+ "es": "Agent Canvas",
+ "ar": "Agent Canvas",
+ "fr": "Agent Canvas",
+ "tr": "Agent Canvas",
+ "de": "Agent Canvas",
+ "uk": "Agent Canvas",
+ "ca": "Agent Canvas"
+ },
+ "SETTINGS$APP_UPDATE_VERSION_LABEL": {
+ "en": "Version",
+ "ja": "バージョン",
+ "zh-CN": "版本",
+ "zh-TW": "版本",
+ "ko-KR": "버전",
+ "no": "Versjon",
+ "it": "Versione",
+ "pt": "Versão",
+ "es": "Versión",
+ "ar": "الإصدار",
+ "fr": "Version",
+ "tr": "Sürüm",
+ "de": "Version",
+ "uk": "Версія",
+ "ca": "Versió"
+ },
+ "SETTINGS$APP_UPDATE_BADGE_UP_TO_DATE": {
+ "en": "Up to date",
+ "ja": "最新",
+ "zh-CN": "已是最新",
+ "zh-TW": "已是最新",
+ "ko-KR": "최신 상태",
+ "no": "Oppdatert",
+ "it": "Aggiornato",
+ "pt": "Atualizado",
+ "es": "Actualizado",
+ "ar": "محدّث",
+ "fr": "À jour",
+ "tr": "Güncel",
+ "de": "Aktuell",
+ "uk": "Актуальна версія",
+ "ca": "Actualitzat"
+ },
+ "SETTINGS$APP_UPDATE_BADGE_UPDATE_AVAILABLE": {
+ "en": "Update available",
+ "ja": "アップデートあり",
+ "zh-CN": "有可用更新",
+ "zh-TW": "有可用更新",
+ "ko-KR": "업데이트 가능",
+ "no": "Oppdatering tilgjengelig",
+ "it": "Aggiornamento disponibile",
+ "pt": "Atualização disponível",
+ "es": "Actualización disponible",
+ "ar": "يتوفر تحديث",
+ "fr": "Mise à jour disponible",
+ "tr": "Güncelleme mevcut",
+ "de": "Update verfügbar",
+ "uk": "Доступне оновлення",
+ "ca": "Actualització disponible"
+ },
+ "SETTINGS$APP_UPDATE_LATEST_MESSAGE": {
+ "en": "You're running the latest version.",
+ "ja": "最新バージョンを実行しています。",
+ "zh-CN": "您正在运行最新版本。",
+ "zh-TW": "您正在執行最新版本。",
+ "ko-KR": "최신 버전을 실행 중입니다.",
+ "no": "Du kjører den nyeste versjonen.",
+ "it": "Stai eseguendo la versione più recente.",
+ "pt": "Você está executando a versão mais recente.",
+ "es": "Estás ejecutando la última versión.",
+ "ar": "أنت تستخدم أحدث إصدار.",
+ "fr": "Vous utilisez la dernière version.",
+ "tr": "En son sürümü kullanıyorsunuz.",
+ "de": "Sie verwenden die neueste Version.",
+ "uk": "Ви використовуєте найновішу версію.",
+ "ca": "Esteu executant la versió més recent."
+ },
+ "SETTINGS$APP_UPDATE_AVAILABLE_MESSAGE": {
+ "en": "Version {{version}} is available.",
+ "ja": "バージョン {{version}} が利用可能です。",
+ "zh-CN": "版本 {{version}} 可用。",
+ "zh-TW": "版本 {{version}} 可用。",
+ "ko-KR": "버전 {{version}}을(를) 사용할 수 있습니다.",
+ "no": "Versjon {{version}} er tilgjengelig.",
+ "it": "È disponibile la versione {{version}}.",
+ "pt": "A versão {{version}} está disponível.",
+ "es": "La versión {{version}} está disponible.",
+ "ar": "الإصدار {{version}} متوفر.",
+ "fr": "La version {{version}} est disponible.",
+ "tr": "{{version}} sürümü mevcut.",
+ "de": "Version {{version}} ist verfügbar.",
+ "uk": "Доступна версія {{version}}.",
+ "ca": "La versió {{version}} està disponible."
+ },
+ "SETTINGS$APP_UPDATE_CHECKING": {
+ "en": "Checking for updates…",
+ "ja": "アップデートを確認中…",
+ "zh-CN": "正在检查更新…",
+ "zh-TW": "正在檢查更新…",
+ "ko-KR": "업데이트 확인 중…",
+ "no": "Ser etter oppdateringer…",
+ "it": "Ricerca aggiornamenti…",
+ "pt": "Verificando atualizações…",
+ "es": "Buscando actualizaciones…",
+ "ar": "جارٍ التحقق من التحديثات…",
+ "fr": "Recherche de mises à jour…",
+ "tr": "Güncellemeler denetleniyor…",
+ "de": "Suche nach Updates…",
+ "uk": "Перевірка оновлень…",
+ "ca": "S'estan cercant actualitzacions…"
+ },
+ "SETTINGS$APP_UPDATE_CHECK_FAILED": {
+ "en": "Couldn't check for updates. Try again later.",
+ "ja": "アップデートを確認できませんでした。後でもう一度お試しください。",
+ "zh-CN": "无法检查更新。请稍后重试。",
+ "zh-TW": "無法檢查更新。請稍後再試。",
+ "ko-KR": "업데이트를 확인할 수 없습니다. 나중에 다시 시도하세요.",
+ "no": "Kunne ikke se etter oppdateringer. Prøv igjen senere.",
+ "it": "Impossibile verificare gli aggiornamenti. Riprova più tardi.",
+ "pt": "Não foi possível verificar atualizações. Tente novamente mais tarde.",
+ "es": "No se pudieron buscar actualizaciones. Inténtalo de nuevo más tarde.",
+ "ar": "تعذر التحقق من التحديثات. حاول مرة أخرى لاحقًا.",
+ "fr": "Impossible de vérifier les mises à jour. Réessayez plus tard.",
+ "tr": "Güncellemeler denetlenemedi. Daha sonra tekrar deneyin.",
+ "de": "Updates konnten nicht geprüft werden. Versuchen Sie es später erneut.",
+ "uk": "Не вдалося перевірити оновлення. Спробуйте пізніше.",
+ "ca": "No s'han pogut cercar actualitzacions. Torneu-ho a provar més tard."
+ },
+ "SETTINGS$APP_UPDATE_CHECK_BUTTON": {
+ "en": "Check for updates",
+ "ja": "アップデートを確認",
+ "zh-CN": "检查更新",
+ "zh-TW": "檢查更新",
+ "ko-KR": "업데이트 확인",
+ "no": "Se etter oppdateringer",
+ "it": "Controlla aggiornamenti",
+ "pt": "Verificar atualizações",
+ "es": "Buscar actualizaciones",
+ "ar": "التحقق من التحديثات",
+ "fr": "Rechercher des mises à jour",
+ "tr": "Güncellemeleri denetle",
+ "de": "Nach Updates suchen",
+ "uk": "Перевірити оновлення",
+ "ca": "Cerca actualitzacions"
+ },
+ "SETTINGS$APP_UPDATE_HOW_TO_UPDATE": {
+ "en": "How to update",
+ "ja": "アップデート方法",
+ "zh-CN": "如何更新",
+ "zh-TW": "如何更新",
+ "ko-KR": "업데이트 방법",
+ "no": "Slik oppdaterer du",
+ "it": "Come aggiornare",
+ "pt": "Como atualizar",
+ "es": "Cómo actualizar",
+ "ar": "كيفية التحديث",
+ "fr": "Comment mettre à jour",
+ "tr": "Nasıl güncellenir",
+ "de": "So aktualisieren Sie",
+ "uk": "Як оновити",
+ "ca": "Com actualitzar"
+ },
+ "SETTINGS$APP_UPDATE_RUN_COMMANDS": {
+ "en": "Run one of the commands below:",
+ "ja": "以下のいずれかのコマンドを実行してください:",
+ "zh-CN": "运行以下任一命令:",
+ "zh-TW": "執行以下任一命令:",
+ "ko-KR": "아래 명령 중 하나를 실행하세요:",
+ "no": "Kjør en av kommandoene nedenfor:",
+ "it": "Esegui uno dei comandi seguenti:",
+ "pt": "Execute um dos comandos abaixo:",
+ "es": "Ejecuta uno de los siguientes comandos:",
+ "ar": "شغّل أحد الأوامر أدناه:",
+ "fr": "Exécutez l'une des commandes ci-dessous :",
+ "tr": "Aşağıdaki komutlardan birini çalıştırın:",
+ "de": "Führen Sie einen der folgenden Befehle aus:",
+ "uk": "Виконайте одну з наведених нижче команд:",
+ "ca": "Executeu una de les ordres següents:"
+ },
+ "SETTINGS$APP_UPDATE_OR": {
+ "en": "or",
+ "ja": "または",
+ "zh-CN": "或",
+ "zh-TW": "或",
+ "ko-KR": "또는",
+ "no": "eller",
+ "it": "oppure",
+ "pt": "ou",
+ "es": "o",
+ "ar": "أو",
+ "fr": "ou",
+ "tr": "veya",
+ "de": "oder",
+ "uk": "або",
+ "ca": "o"
+ },
+ "SETTINGS$APP_UPDATE_RELEASE_NOTES": {
+ "en": "View release notes",
+ "ja": "リリースノートを表示",
+ "zh-CN": "查看发行说明",
+ "zh-TW": "檢視版本資訊",
+ "ko-KR": "릴리스 노트 보기",
+ "no": "Se utgivelsesnotater",
+ "it": "Visualizza le note di rilascio",
+ "pt": "Ver notas de versão",
+ "es": "Ver notas de la versión",
+ "ar": "عرض ملاحظات الإصدار",
+ "fr": "Voir les notes de version",
+ "tr": "Sürüm notlarını görüntüle",
+ "de": "Versionshinweise anzeigen",
+ "uk": "Переглянути примітки до випуску",
+ "ca": "Mostra les notes de la versió"
}
}