The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(ui): keep the installed service worker fresh on parked tabs (#12198)
Devin Foleyca02d2463af3
diff --git a/server/src/__tests__/static-ui-cache.test.ts b/server/src/__tests__/static-ui-cache.test.tsnew file mode 100644index 0000000000..1285d2bd0e--- /dev/null+++ b/server/src/__tests__/static-ui-cache.test.ts@@ -0,0 +1,22 @@+import path from "node:path";+import { describe, expect, it } from "vitest";+import { staticUiCacheControl } from "../static-ui-cache.js";++describe("staticUiCacheControl", () => {+ it("forces revalidation for index.html", () => {+ expect(staticUiCacheControl(path.join("/srv", "ui-dist", "index.html"))).toBe("no-cache");+ });++ it("forces revalidation for the service-worker script", () => {+ // Browsers refresh an installed worker only by re-fetching /sw.js; a+ // cached copy pins every client on old worker code for the TTL.+ expect(staticUiCacheControl(path.join("/srv", "ui-dist", "sw.js"))).toBe("no-cache");+ });++ it("leaves other static files on the middleware default", () => {+ expect(staticUiCacheControl(path.join("/srv", "ui-dist", "favicon.ico"))).toBeUndefined();+ expect(staticUiCacheControl(path.join("/srv", "ui-dist", "robots.txt"))).toBeUndefined();+ // Lookalikes keep the default: only the exact worker filename is special.+ expect(staticUiCacheControl(path.join("/srv", "ui-dist", "sw.js.map"))).toBeUndefined();+ });+});diff --git a/server/src/app.ts b/server/src/app.tsindex 5c16989a23..e7d4230ca8 100644--- a/server/src/app.ts+++ b/server/src/app.ts@@ -85,6 +85,7 @@ import { mcpGatewayProtocolRoutes, toolGatewayRoutes } from "./routes/tool-gatewimport { adapterRoutes } from "./routes/adapters.js";import { pluginUiStaticRoutes } from "./routes/plugin-ui-static.js";import { readBrandedStaticIndexHtml } from "./static-index-html.js";+import { staticUiCacheControl } from "./static-ui-cache.js";import { applyUiBranding } from "./ui-branding.js";import { logger } from "./middleware/logger.js";import { DEFAULT_LOCAL_PLUGIN_DIR, pluginLoader, type PluginLoader } from "./services/plugin-loader.js";@@ -686,15 +687,15 @@ export async function createApp();// Non-hashed static files (favicon.ico, manifest, robots.txt, etc.):// short cache so operators who swap them out see the new version- // reasonably fast. Override for `index.html` specifically — it is- // served by this middleware for `/` and `/index.html`, and it must- // never outlive the asset hashes it points at.+ // reasonably fast, with must-revalidate overrides for index.html and+ // sw.js (see staticUiCacheControl for why those two).app.use(express.static(uiDist, {maxAge: "1h",setHeaders(res, filePath) {- if (path.basename(filePath) === "index.html") {- res.set("Cache-Control", "no-cache");+ const override = staticUiCacheControl(filePath);+ if (override) {+ res.set("Cache-Control", override);}},}),diff --git a/server/src/static-ui-cache.ts b/server/src/static-ui-cache.tsnew file mode 100644index 0000000000..7555036bd5--- /dev/null+++ b/server/src/static-ui-cache.ts@@ -0,0 +1,19 @@+import path from "node:path";++/**+ * Cache-Control override for non-hashed UI static files (everything outside+ * /assets, which is content-hashed and immutable). Two files must always be+ * revalidated:+ *+ * - `index.html` must never outlive the asset hashes it points at.+ * - `sw.js` is the browser's only channel for updating an installed service+ * worker: clients re-fetch this exact URL to discover new worker code, so+ * any cache TTL here delays every client's update by that long on top of+ * the browser's own update timer.+ *+ * Returns undefined for files where the middleware's default TTL applies.+ */+export function staticUiCacheControl(filePath: string): "no-cache" | undefined {+ const basename = path.basename(filePath);+ return basename === "index.html" || basename === "sw.js" ? "no-cache" : undefined;+}diff --git a/ui/src/lib/service-worker-updates.test.ts b/ui/src/lib/service-worker-updates.test.tsnew file mode 100644index 0000000000..74709abc67--- /dev/null+++ b/ui/src/lib/service-worker-updates.test.ts@@ -0,0 +1,170 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { startServiceWorkerUpdates } from "./service-worker-updates";++type Listener = () => void;++function fakeContainer(opts: { controlled: boolean }) {+ const listeners = new Map<string, Set<Listener>>();+ const registration = { update: vi.fn(() => Promise.resolve()) };+ const container = {+ controller: opts.controlled ? ({} as ServiceWorker) : null,+ register: vi.fn(() => Promise.resolve(registration)),+ addEventListener: vi.fn((type: string, listener: Listener) => {+ if (!listeners.has(type)) listeners.set(type, new Set());+ listeners.get(type)!.add(listener);+ }),+ removeEventListener: vi.fn((type: string, listener: Listener) => {+ listeners.get(type)?.delete(listener);+ }),+ };+ const emit = (type: string) => {+ for (const listener of listeners.get(type) ?? []) listener();+ };+ return { container: container as unknown as ServiceWorkerContainer, registration, emit, listeners };+}++function fakeDocument(initialVisibility: DocumentVisibilityState = "visible") {+ const listeners = new Map<string, Set<Listener>>();+ const doc = {+ visibilityState: initialVisibility,+ addEventListener: (type: string, listener: Listener) => {+ if (!listeners.has(type)) listeners.set(type, new Set());+ listeners.get(type)!.add(listener);+ },+ removeEventListener: (type: string, listener: Listener) => {+ listeners.get(type)?.delete(listener);+ },+ };+ const emit = (type: string) => {+ for (const listener of listeners.get(type) ?? []) listener();+ };+ return { doc: doc as unknown as Document & { visibilityState: DocumentVisibilityState }, emit, listeners };+}++describe("startServiceWorkerUpdates", () => {+ beforeEach(() => {+ vi.useFakeTimers();+ });++ afterEach(() => {+ vi.useRealTimers();+ });++ it("registers /sw.js", async () => {+ const { container } = fakeContainer({ controlled: false });+ const { doc } = fakeDocument();+ startServiceWorkerUpdates({ container, documentRef: doc, reload: vi.fn() });+ expect(container.register).toHaveBeenCalledWith("/sw.js");+ });++ it("reloads once when a new worker takes over a hidden, already-controlled page", async () => {+ const { container, emit } = fakeContainer({ controlled: true });+ const { doc } = fakeDocument("hidden");+ const reload = vi.fn();+ startServiceWorkerUpdates({ container, documentRef: doc, reload });++ emit("controllerchange");+ emit("controllerchange");+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("defers the reload to the next hidden transition when the takeover lands mid-session", async () => {+ const { container, emit } = fakeContainer({ controlled: true });+ const docState = fakeDocument("visible");+ const reload = vi.fn();+ startServiceWorkerUpdates({ container, documentRef: docState.doc, reload });++ emit("controllerchange");+ // The user is looking at the page: never yank it out from under them.+ expect(reload).not.toHaveBeenCalled();++ docState.doc.visibilityState = "hidden";+ docState.emit("visibilitychange");+ expect(reload).toHaveBeenCalledTimes(1);++ docState.emit("visibilitychange");+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("does not reload on a first-ever install", async () => {+ const { container, emit } = fakeContainer({ controlled: false });+ const { doc } = fakeDocument("hidden");+ const reload = vi.fn();+ startServiceWorkerUpdates({ container, documentRef: doc, reload });++ emit("controllerchange");+ expect(reload).not.toHaveBeenCalled();+ });++ it("reloads when a later deploy replaces the worker a first-visit tab installed", async () => {+ const { container, emit } = fakeContainer({ controlled: false });+ const { doc } = fakeDocument("hidden");+ const reload = vi.fn();+ startServiceWorkerUpdates({ container, documentRef: doc, reload });++ // First takeover: the fresh install controls the page, no reload.+ emit("controllerchange");+ expect(reload).not.toHaveBeenCalled();++ // A deploy lands while the same tab is still open: now the controller+ // change means newer code, and the hidden tab reloads onto it.+ emit("controllerchange");+ expect(reload).toHaveBeenCalledTimes(1);+ });++ it("checks for updates when the tab becomes visible", async () => {+ const { container, registration, emit } = fakeContainer({ controlled: true });+ const docState = fakeDocument("hidden");+ startServiceWorkerUpdates({ container, documentRef: docState.doc, reload: vi.fn() });+ await vi.waitFor(() => expect(container.register).toHaveBeenCalled());+ // Let the register() promise settle so the registration is captured.+ await Promise.resolve();++ docState.emit("visibilitychange");+ expect(registration.update).not.toHaveBeenCalled();++ docState.doc.visibilityState = "visible";+ docState.emit("visibilitychange");+ expect(registration.update).toHaveBeenCalledTimes(1);+ });++ it("checks for updates on the timer", async () => {+ const { container, registration } = fakeContainer({ controlled: true });+ const { doc } = fakeDocument();+ startServiceWorkerUpdates({+ container,+ documentRef: doc,+ reload: vi.fn(),+ updateIntervalMs: 1000,+ });+ await Promise.resolve();++ vi.advanceTimersByTime(3000);+ expect(registration.update).toHaveBeenCalledTimes(3);+ });++ it("stops listening and ticking after cleanup", async () => {+ const { container, registration, emit, listeners } = fakeContainer({ controlled: true });+ const docState = fakeDocument();+ const reload = vi.fn();+ const stop = startServiceWorkerUpdates({+ container,+ documentRef: docState.doc,+ reload,+ updateIntervalMs: 1000,+ });+ await Promise.resolve();++ stop();+ emit("controllerchange");+ docState.emit("visibilitychange");+ vi.advanceTimersByTime(5000);+ expect(reload).not.toHaveBeenCalled();+ expect(registration.update).not.toHaveBeenCalled();+ expect(listeners.get("controllerchange")?.size ?? 0).toBe(0);+ });++ it("is a no-op without a service worker container", () => {+ expect(() => startServiceWorkerUpdates({ reload: vi.fn() })()).not.toThrow();+ });+});diff --git a/ui/src/lib/service-worker-updates.ts b/ui/src/lib/service-worker-updates.tsnew file mode 100644index 0000000000..7ce1d33739--- /dev/null+++ b/ui/src/lib/service-worker-updates.ts@@ -0,0 +1,101 @@+/**+ * Registers `/sw.js` and keeps the installed worker fresh on a long-lived tab.+ *+ * Browsers only re-fetch a service-worker script on navigation or on a ~24h+ * timer. Paperclip is a parked-tab SPA — a tab can stay open for weeks without+ * a single navigation — so without explicit update checks an old worker (and+ * the app shell it cached) can outlive a deploy indefinitely. The symptom is+ * invisible: the tab just keeps running the old bundle.+ *+ * Two behaviors close the gap:+ * - `registration.update()` runs when the tab becomes visible and on an+ * hourly timer, so parked tabs learn about new workers without navigating.+ * - When a new worker takes control (`controllerchange`), the page reloads+ * once so the fresh shell actually replaces the running bundle — but only+ * while the tab is hidden, so an update landing mid-session never yanks+ * the page out from under the user; a takeover while visible defers the+ * reload to the next time the tab is hidden. First-ever installs skip the+ * reload entirely: an uncontrolled page is already running the code the+ * server just handed it.+ */+const DEFAULT_UPDATE_INTERVAL_MS = 60 * 60 * 1000;++export function startServiceWorkerUpdates(+ options: {+ container?: ServiceWorkerContainer;+ documentRef?: Document;+ reload?: () => void;+ updateIntervalMs?: number;+ } = {},+): () => void {+ const container =+ options.container ??+ (typeof navigator !== "undefined" && "serviceWorker" in navigator+ ? navigator.serviceWorker+ : undefined);+ if (!container) {+ return () => {};+ }+ const documentRef = options.documentRef ?? document;+ const reload = options.reload ?? (() => window.location.reload());+ const updateIntervalMs = options.updateIntervalMs ?? DEFAULT_UPDATE_INTERVAL_MS;++ // Only a page that is already worker-controlled is running+ // potentially-stale code when the controller changes; a first-ever+ // install taking control is caching the very bundle the page is running,+ // so reloading would be a no-op. The flag is promoted on that first+ // takeover: any later controller change on this (possibly weeks-old) tab+ // does mean newer code exists.+ let wasControlled = Boolean(container.controller);+ let reloaded = false;+ let reloadPending = false;+ const applyUpdate = () => {+ if (reloaded) return;+ reloaded = true;+ reload();+ };+ const onControllerChange = () => {+ if (!wasControlled) {+ wasControlled = true;+ return;+ }+ if (documentRef.visibilityState === "hidden") {+ applyUpdate();+ } else {+ reloadPending = true;+ }+ };+ container.addEventListener("controllerchange", onControllerChange);++ let registration: ServiceWorkerRegistration | undefined;+ const checkForUpdates = () => {+ // update() rejects while offline or mid-deploy; the next visibility+ // change or timer tick retries, so failures are deliberately swallowed.+ void registration?.update().catch(() => {});+ };+ const onVisibilityChange = () => {+ if (documentRef.visibilityState === "visible") {+ checkForUpdates();+ } else if (reloadPending) {+ applyUpdate();+ }+ };+ documentRef.addEventListener("visibilitychange", onVisibilityChange);+ const intervalId = setInterval(checkForUpdates, updateIntervalMs);++ void container+ .register("/sw.js")+ .then((reg) => {+ registration = reg;+ })+ .catch(() => {+ // Registration can fail in private windows or hardened browsers; the+ // app works without a worker, it just loses the offline fallback.+ });++ return () => {+ container.removeEventListener("controllerchange", onControllerChange);+ documentRef.removeEventListener("visibilitychange", onVisibilityChange);+ clearInterval(intervalId);+ };+}diff --git a/ui/src/main.tsx b/ui/src/main.tsxindex 2766c51e1e..c6aa4eb559 100644--- a/ui/src/main.tsx+++ b/ui/src/main.tsx@@ -19,6 +19,7 @@ import { TooltipProvider } from "@/components/ui/tooltip";import { initPluginBridge } from "./plugins/bridge-init";import { PluginLauncherProvider } from "./plugins/launchers";import { startPerfMeasureReaper } from "./lib/perf-measure-reaper";+import { startServiceWorkerUpdates } from "./lib/service-worker-updates";import "@mdxeditor/editor/style.css";import "./index.css";@@ -29,11 +30,13 @@ initPluginBridge(React, ReactDOM);// accumulate into millions of native objects (GBs). Reap them periodically.startPerfMeasureReaper();-if ("serviceWorker" in navigator) {- window.addEventListener("load", () => {- navigator.serviceWorker.register("/sw.js");- });-}+// Parked SPA tabs never navigate, so beyond registering the worker this also+// re-checks /sw.js on tab focus and hourly, and applies a discovered update+// with one reload while the tab is hidden — otherwise an old worker and its+// cached shell can outlive a deploy indefinitely.+window.addEventListener("load", () => {+ startServiceWorkerUpdates();+});const queryClient = new QueryClient({defaultOptions: {