@xpufx/paseo-plugin-updates 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xpufx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# plugin-updates
+
+Git-source update monitor and updater for [Paseo](https://github.com/getpaseo/paseo) plugins (v0.8+).
+
+<table align="center">
+  <tr>
+    <td align="center"><strong>main</strong><br><img src="screenshots/plugin-updates-main.jpg" alt="Plugin updates — main view" width="300"></td>
+    <td align="center"><strong>updating</strong><br><img src="screenshots/plugin-updates-action.jpg" alt="Plugin updates — updating" width="300"></td>
+  </tr>
+</table>
+
+Adds a header button to every workspace that opens a popover listing the installed plugins. Each row reports whether the plugin's installed git source is current, behind, pinned, missing, or has no upstream, and offers a one-click update when a pullable change exists.
+
+Built on [paseo-plugin-helper](https://github.com/xpufx/paseo/tree/main/packages/paseo-plugin-helper), the shared Paseo plugin runtime.
+
+> [!NOTE]
+> **Prerequisites & Platform Support**:
+> - The system `git` CLI must be available, because update checks and pulls shell out to `git`.
+> - Developed and tested primarily on **Linux**.
+
+## Core Capabilities
+
+### 1. Workspace Header Button
+- Registers a header button once per workspace, titled **Plugin updates**, that opens a popover listing every installed plugin.
+- The button shows a refresh glyph while a check is running, and a status dot in the corner: green when everything is fresh, amber while checking or when an update is available, and red when a check fails.
+
+### 2. Per-plugin Git Status
+Each row resolves the plugin to its git repository root, ref, and subdirectory, then probes the remote to classify the install:
+
+- **current**: the local commit or subdirectory tree matches the tracked ref, or the local checkout is ahead of the remote.
+- **behind**: the remote ref has commits the local checkout does not, so an update is available.
+- **pinned**: the install is pinned to a fixed tag or commit. Pinned installs are report only; nothing is ever pulled for them.
+- **no-upstream**: no upstream remote is configured, or the tracked branch or tag no longer exists on the remote.
+- **missing**: the remote is reachable but the plugin subdirectory does not exist at the tracked ref.
+- **unpinned**: a detached HEAD, or a managed install with no recorded ref. Report only.
+- **not-a-repo**: the plugin is not a git checkout, so no git update is possible.
+- **error**: the check itself failed, for example because the remote was unreachable.
+
+### 3. Per-subdirectory Scoping
+- Plugins installed from a monorepo subpath track only that subdirectory tree. A commit that touches other paths in the same repository does not register as an update.
+- The row shows the resolved **Subdir** (`(repo root)` when the plugin is the repository root), alongside the local and remote tree hashes and the tracked ref.
+
+### 4. Source Links
+- Each row resolves a browsable source URL from the remote the plugin was installed from, falling back to `package.json` `repository` and `homepage` metadata when no install remote exists.
+- GitHub, GitLab, and unknown forges get an appropriate glyph, and links deep-link into the subdirectory for GitHub (`/tree/<ref>/<subdir>`) and Forgejo/Gitea-style (`/src/branch/<ref>/<subdir>`) hosts.
+- A `dirty` badge appears on a directory install when the plugin scope has uncommitted changes.
+
+### 5. Update Action
+- Available updates show an **Update** button in the row. After a failed pull that needs an override, the button becomes **Force update**.
+- **git-managed installs** delegate to `paseo plugin update <id>`.
+- **directory (path-linked) installs** resolve the repository root and run a fast-forward `git pull`. The pull is refused when the working tree is dirty unless forced, and refused when the local branch has diverged from its upstream.
+- After a successful pull, every plugin that shares the same repository root is reloaded.
+- When more than one plugin has an update, an **Update all** button appears. If any failure requires an override, **Force update all** is offered instead.
+
+### 6. Orphaned Directory Flagging
+- Directories left behind in Paseo's managed plugin location by an uninstalled or failed install are listed in a separate **Orphaned directories** section with a name and path.
+- Orphans are reported only; they are never probed or updated.
+
+### 7. Live Refresh
+- The popover re-checks on a 30 second interval and on demand through the refresh button, and reports the available update count in its header.
+
+## Installation
+
+Install from the public monorepo subpath (GitHub shorthand):
+
+```sh
+paseo plugin add xpufx/paseo --path plugins/plugin-updates
+```
+
+> [!NOTE]
+> Bare `owner/repo` shorthand resolves against **GitHub** only. For any other forge, pass the full git URL instead, for example `https://git.example.com/owner/repo`.
+
+For local development:
+
+```sh
+git clone https://github.com/xpufx/paseo.git
+cd paseo
+paseo plugin add ./plugins/plugin-updates
+```
+
+## Usage & Configuration
+
+- No settings are required. The header button registers automatically in each workspace that has an agent session.
+- Open the button to see installed plugins, their status, and available updates, then use the row **Update** button or **Update all** to pull and reload.
+- Checks run against the plugin's install remote only, so a fork or mirror installed as the source is what gets compared.
+- Pulls run with `--ff-only`. A dirty working tree or a diverged branch must be reconciled manually before an update can apply.
+
+## Limitations
+
+- **Local git installs are report-only.** With no upstream remote or recorded ref, there is nothing to compare against or pull, so no **Update** button is offered for them. Use a git remote + subpath to get updates.
+
+## Development
+
+```sh
+# Typecheck
+npm run typecheck --workspace=plugins/plugin-updates
+
+# Typecheck plus the test suite (tsx --test)
+npm run test --workspace=plugins/plugin-updates
+
+# Reload in a running Paseo daemon
+paseo plugin reload plugin-updates
+paseo plugin logs plugin-updates
+```
+
+## License
+
+MIT

package/client/orphans.ts

@@ -0,0 +1,37 @@
+import type { PluginUpdate } from "../shared/updates";
+
+export interface OrphanEntry {
+  name: string;
+  path: string;
+}
+
+export interface OrphanSection {
+  title: string;
+  detail: string;
+  items: OrphanEntry[];
+}
+
+function orphanName(id: string): string {
+  const prefix = "orphaned:";
+  return id.startsWith(prefix) ? id.slice(prefix.length) : id;
+}
+
+function orphanDetail(count: number): string {
+  return count === 1
+    ? "Leftover managed directory from an uninstalled or failed install — not probed"
+    : "Leftover managed directories from uninstalled or failed installs — not probed";
+}
+
+export function partitionedRows(plugins: PluginUpdate[]): PluginUpdate[] {
+  return plugins.filter((plugin) => plugin.status !== "orphaned");
+}
+
+export function buildOrphanSection(plugins: PluginUpdate[]): OrphanSection | null {
+  const orphans = plugins.filter((plugin) => plugin.status === "orphaned");
+  if (orphans.length === 0) return null;
+  return {
+    title: "Orphaned directories",
+    detail: orphanDetail(orphans.length),
+    items: orphans.map((plugin) => ({ name: orphanName(plugin.id), path: plugin.path })),
+  };
+}

package/client/updates.tsx

@@ -0,0 +1,510 @@
+import type {
+  PluginButtonContentProps,
+  PluginButtonIconProps,
+  PluginButtonRegistration,
+} from "@getpaseo/plugin/client";
+import { useRpc } from "@getpaseo/plugin/client";
+import { Icon, ScrollView, useToast } from "@getpaseo/plugin/client/react-native";
+import {
+  Badge,
+  Button,
+  Card,
+  EmptyState,
+  KeyValue,
+  KeyValueGroup,
+  PluginThemeProvider,
+  ProgressBar,
+  Row,
+  SectionHeader,
+  StatusDot,
+  usePluginTheme,
+} from "paseo-plugin-helper/client";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import { ActivityIndicator, Linking, Text, View } from "react-native";
+import {
+  pluginUpdatesCheckRpc,
+  pluginUpdatesUpdateAllRpc,
+  pluginUpdatesUpdateRpc,
+  resolveSourceRef,
+  shortHash,
+  type PluginUpdate,
+} from "../shared/updates";
+import { buildOrphanSection, partitionedRows, type OrphanSection } from "./orphans";
+
+const QUERY_KEY = ["plugin-updates"];
+const POLL_MS = 30_000;
+
+function usePluginUpdates(workspaceId: string) {
+  const check = useRpc(pluginUpdatesCheckRpc);
+  return useQuery({
+    queryKey: [...QUERY_KEY, workspaceId],
+    queryFn: () => check({ workspaceId }),
+    refetchInterval: POLL_MS,
+    retry: false,
+  });
+}
+
+function statusVariant(status: PluginUpdate["status"]): "success" | "warning" | "danger" | "neutral" {
+  if (status === "behind") return "warning";
+  if (status === "error") return "danger";
+  if (status === "current") return "success";
+  return "neutral";
+}
+
+function fallbackDetail(plugin: PluginUpdate): string {
+  if (plugin.detail) return plugin.detail;
+  switch (plugin.status) {
+    case "behind":
+      return "Update available";
+    case "current":
+      return "Up to date";
+    case "pinned":
+      return "Pinned to a fixed ref — report only";
+    case "not-a-repo":
+      return "Not a git repository — no git update possible";
+    case "unpinned":
+      return "Detached HEAD — no upstream to compare (report only)";
+    case "no-upstream":
+      return "No upstream remote configured (report only)";
+    case "missing":
+      return "Plugin does not exist at the source it was installed from.";
+    case "orphaned":
+      return "Leftover managed directory from a failed install — not probed";
+    case "checking":
+      return "Checking…";
+    default:
+      return plugin.error || "Check failed";
+  }
+}
+
+function reportOnlyNote(plugin: PluginUpdate): string | null {
+  const status = plugin.status;
+  if (status === "not-a-repo") return "Not a git checkout — update it from the workspace instead.";
+  if (status === "orphaned") return "Orphaned managed directory — safe to remove if unused.";
+  if (status === "pinned") {
+    return plugin.refKind === "tag"
+      ? "Pinned to a tag — tags are never auto-updated. Reinstall to move to another tag."
+      : "Pinned by commit — immutable, no update is ever offered.";
+  }
+  if (status === "unpinned" || status === "no-upstream") return "Report only — no upstream remote to update from.";
+  return null;
+}
+
+function refLabel(plugin: PluginUpdate): string {
+  if (!plugin.ref) return "-";
+  return plugin.refKind ? `${plugin.refKind} · ${plugin.ref}` : plugin.ref;
+}
+
+function hashValue(value: string | null): string | null {
+  return value ? shortHash(value) : null;
+}
+
+function PluginRow({
+  plugin,
+  updating,
+  forceNeeded,
+  onUpdate,
+}: {
+  plugin: PluginUpdate;
+  updating: boolean;
+  forceNeeded: boolean;
+  onUpdate: (pluginId: string, force: boolean) => void;
+}) {
+  const { colors, typography, padding } = usePluginTheme();
+  const detail = fallbackDetail(plugin);
+  const note = reportOnlyNote(plugin);
+  const isOrphan = plugin.status === "orphaned";
+  const version = hashValue(plugin.workingTree ?? plugin.localTree);
+  const source = resolveSourceRef(plugin.sourceUrl);
+  // Errors carry actionable text; clamp only the one-line status sentences.
+  const detailLines = plugin.error ? undefined : 1;
+  return (
+    <Card variant="elevated">
+      <View style={{ gap: padding.gap }}>
+        <Row align="center">
+          <StatusDot variant={statusVariant(plugin.status)} pulse={plugin.status === "checking"} />
+          <Text style={{ color: colors.foreground, ...typography.bodyStrong, flex: 1 }}>{plugin.id}</Text>
+          {source ? (
+            <Button
+              icon={source.icon}
+              label={source.label}
+              variant="ghost"
+              size="sm"
+              accessibilityLabel="Open source"
+              onPress={() => {
+                void Linking.openURL(source.url).catch(() => {});
+              }}
+            />
+          ) : null}
+          {plugin.dirty === true && !isOrphan ? <Badge label="dirty" variant="warning" dot /> : null}
+          {plugin.updateAvailable && !isOrphan ? (
+            <Button
+              label={forceNeeded ? "Force update" : "Update"}
+              variant={forceNeeded ? "primary" : "secondary"}
+              size="sm"
+              loading={updating}
+              disabled={updating}
+              onPress={() => onUpdate(plugin.id, forceNeeded)}
+            />
+          ) : null}
+        </Row>
+        <Text selectable numberOfLines={detailLines} style={{ color: colors.foregroundMuted, ...typography.caption }}>
+          {detail}
+        </Text>
+        {note ? (
+          <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>{note}</Text>
+        ) : null}
+        {isOrphan ? null : (
+          <>
+            <KeyValueGroup columns={2} collapse="never" minColumnWidth={180} gap={0}>
+              <KeyValue
+                layout="inline"
+                label="Version"
+                value={version}
+                subValue={plugin.workingTree ? "working tree" : undefined}
+                mono
+                copyable
+              />
+              <KeyValue layout="inline" label="Remote" value={hashValue(plugin.remoteTree)} mono copyable />
+              <KeyValue layout="inline" label="Ref" value={refLabel(plugin)} truncate="end" />
+              <KeyValue
+                layout="inline"
+                label="Subdir"
+                value={plugin.subdir === "" ? "(repo root)" : plugin.subdir}
+                truncate="path"
+              />
+            </KeyValueGroup>
+            {plugin.latestChange?.subject ? (
+              <Text selectable numberOfLines={1} style={{ color: colors.foregroundMuted, ...typography.caption }}>
+                Latest remote change: {plugin.latestChange.subject}
+                {plugin.latestChange.date ? ` (${plugin.latestChange.date})` : ""}
+              </Text>
+            ) : null}
+          </>
+        )}
+      </View>
+    </Card>
+  );
+}
+
+function OrphanSection({ section }: { section: OrphanSection }) {
+  const { colors, typography } = usePluginTheme();
+  return (
+    <View style={{ gap: 6 }}>
+      <SectionHeader title={section.title} count={section.items.length} />
+      <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>{section.detail}</Text>
+      <View style={{ gap: 6 }}>
+        {section.items.map((item) => (
+          <View key={item.name} style={{ gap: 1 }}>
+            <Text selectable style={{ color: colors.foreground, ...typography.bodyStrong }}>
+              {item.name}
+            </Text>
+            <Text selectable numberOfLines={1} style={{ color: colors.foregroundMuted, ...typography.caption }}>
+              {item.path}
+            </Text>
+          </View>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+function PluginUpdatesIconInner(props: PluginButtonIconProps) {
+  const { data, isFetching, isError } = usePluginUpdates(props.workspaceId);
+  const stale = data?.plugins.some((plugin) => plugin.updateAvailable) ?? false;
+  const failed = isError || data?.plugins.some((plugin) => plugin.status === "error") === true;
+  const color = failed
+    ? props.theme.colors.statusDanger || "#ef4444"
+    : stale
+      ? props.theme.colors.statusWarning || "#f59e0b"
+      : props.color;
+  return (
+    <View style={{ width: props.size, height: props.size, alignItems: "center", justifyContent: "center" }}>
+      <Icon name={isFetching ? "RefreshCw" : "Package"} size={props.size} color={color} />
+      <View
+        accessibilityLabel={isFetching ? "Checking plugin updates" : stale ? "Plugin updates available" : "Plugins fresh"}
+        style={{
+          position: "absolute",
+          right: -1,
+          top: -1,
+          width: 7,
+          height: 7,
+          borderRadius: 4,
+          backgroundColor: isFetching
+            ? props.theme.colors.statusWarning || "#f59e0b"
+            : failed
+              ? props.theme.colors.statusDanger || "#ef4444"
+              : stale
+                ? props.theme.colors.statusWarning || "#f59e0b"
+                : props.theme.colors.statusSuccess || "#22c55e",
+        }}
+      />
+    </View>
+  );
+}
+
+export function PluginUpdatesIcon(props: PluginButtonIconProps) {
+  return (
+    <PluginThemeProvider theme={{ colors: props.theme.colors }}>
+      <PluginUpdatesIconInner {...props} />
+    </PluginThemeProvider>
+  );
+}
+
+interface Failure {
+  pluginId: string;
+  error: string;
+  requiresForce: boolean;
+}
+
+function PluginUpdatesPopoverInner(props: PluginButtonContentProps) {
+  const { colors, typography, padding } = usePluginTheme();
+  const toast = useToast();
+  const queryClient = useQueryClient();
+  const query = usePluginUpdates(props.workspaceId);
+  const update = useRpc(pluginUpdatesUpdateRpc);
+  const updateAll = useRpc(pluginUpdatesUpdateAllRpc);
+  const [activeUpdate, setActiveUpdate] = useState<string | "all" | null>(null);
+  const [progress, setProgress] = useState(0);
+  const [failures, setFailures] = useState<Failure[]>([]);
+
+  const plugins = query.data?.plugins ?? [];
+  const rows = partitionedRows(plugins);
+  const orphanSection = buildOrphanSection(plugins);
+  const staleCount = plugins.filter((plugin) => plugin.updateAvailable).length;
+  const forceCount = failures.filter((failure) => failure.requiresForce).length;
+
+  const refresh = async () => {
+    try {
+      setFailures([]);
+      await query.refetch();
+    } catch (error) {
+      toast.show(error instanceof Error ? error.message : String(error), { variant: "error" });
+    }
+  };
+
+  const recordFailure = (failure: Failure) => {
+    setFailures((current) => [
+      ...current.filter((item) => item.pluginId !== failure.pluginId),
+      failure,
+    ]);
+  };
+
+  const clearFailure = (pluginId: string) => {
+    setFailures((current) => current.filter((failure) => failure.pluginId !== pluginId));
+  };
+
+  const runUpdate = async (pluginId: string, force = false) => {
+    setActiveUpdate(pluginId);
+    setProgress(0.25);
+    try {
+      const result = await update({ workspaceId: props.workspaceId, pluginId, force });
+      if (result.status === "error") {
+        recordFailure({
+          pluginId,
+          error: result.error || "Update failed",
+          requiresForce: result.requiresForce === true,
+        });
+        toast.show(result.error || `Failed to update ${pluginId}`, { variant: "error" });
+      } else {
+        clearFailure(pluginId);
+        toast.show(`${pluginId} updated`, { variant: "success" });
+      }
+      setProgress(1);
+      await queryClient.invalidateQueries({ queryKey: [...QUERY_KEY, props.workspaceId] });
+    } catch (error) {
+      toast.show(error instanceof Error ? error.message : String(error), { variant: "error" });
+    } finally {
+      setActiveUpdate(null);
+    }
+  };
+
+  const runUpdateAll = async (force = false) => {
+    setActiveUpdate("all");
+    setProgress(0.1);
+    try {
+      const result = await updateAll({ workspaceId: props.workspaceId, force });
+      const failed = result.results.filter((item) => item.status === "error");
+      setFailures(
+        failed.map((item) => ({
+          pluginId: item.pluginId,
+          error: item.error || "Update failed",
+          requiresForce: item.requiresForce === true,
+        })),
+      );
+      setProgress(1);
+      if (failed.length > 0) {
+        toast.show(`${failed.length} plugin update${failed.length === 1 ? "" : "s"} failed`, {
+          variant: "error",
+        });
+      } else {
+        toast.show("All plugins updated", { variant: "success" });
+      }
+      await queryClient.invalidateQueries({ queryKey: [...QUERY_KEY, props.workspaceId] });
+    } catch (error) {
+      toast.show(error instanceof Error ? error.message : String(error), { variant: "error" });
+    } finally {
+      setActiveUpdate(null);
+    }
+  };
+
+  useEffect(() => {
+    if (query.isError) {
+      toast.show("Unable to check plugin updates", { variant: "error" });
+    }
+  }, [query.isError, toast]);
+
+  return (
+    <PluginThemeProvider theme={props.theme} layout={props.layout}>
+      <ScrollView
+        contentContainerStyle={{
+          paddingHorizontal: padding.horizontal,
+          paddingVertical: padding.vertical,
+          gap: padding.gap,
+        }}
+      >
+        <Row align="center">
+          <View style={{ flex: 1 }}>
+            <Text style={{ color: colors.foreground, ...typography.heading }}>Plugin updates</Text>
+            <Text style={{ color: colors.foregroundMuted, ...typography.caption }}>
+              {query.isFetching ? "Checking installed plugins…" : `${staleCount} update${staleCount === 1 ? "" : "s"} available`}
+            </Text>
+          </View>
+          <Button
+            icon="RefreshCw"
+            variant="ghost"
+            size="sm"
+            loading={query.isFetching}
+            disabled={query.isFetching || activeUpdate !== null}
+            accessibilityLabel="Refresh plugin update check"
+            onPress={refresh}
+          />
+        </Row>
+        {activeUpdate ? <ProgressBar value={progress} autoStatusColor label="Updating plugins" showValueText /> : null}
+        {query.isLoading && !query.data ? (
+          <View style={{ alignItems: "center", paddingVertical: padding.vertical * 2 }}>
+            <ActivityIndicator color={colors.foregroundMuted} />
+          </View>
+        ) : plugins.length === 0 ? (
+          <EmptyState title="No installed plugins" description="Paseo did not report any installed plugins." />
+        ) : (
+          <>
+            {rows.map((plugin) => (
+              <PluginRow
+                key={plugin.id}
+                plugin={plugin}
+                updating={activeUpdate === plugin.id}
+                forceNeeded={failures.some((failure) => failure.pluginId === plugin.id && failure.requiresForce)}
+                onUpdate={runUpdate}
+              />
+            ))}
+            {orphanSection ? <OrphanSection section={orphanSection} /> : null}
+          </>
+        )}
+        {failures.map((failure) => (
+          <Card key={`failure-${failure.pluginId}`} variant="elevated">
+            <View style={{ gap: padding.gap }}>
+              <Row align="center">
+                <StatusDot variant="danger" />
+                <Text style={{ color: colors.statusDanger, ...typography.bodyStrong, flex: 1 }}>
+                  {failure.pluginId} update failed
+                </Text>
+                {failure.requiresForce ? (
+                  <Button
+                    label="Force"
+                    variant="secondary"
+                    size="sm"
+                    loading={activeUpdate === failure.pluginId}
+                    disabled={activeUpdate !== null}
+                    onPress={() => runUpdate(failure.pluginId, true)}
+                  />
+                ) : null}
+              </Row>
+              <Text selectable style={{ color: colors.foregroundMuted, ...typography.caption }}>
+                {failure.error}
+              </Text>
+            </View>
+          </Card>
+        ))}
+        {forceCount > 0 ? (
+          <Button
+            label="Force update all"
+            variant="secondary"
+            icon="AlertTriangle"
+            loading={activeUpdate === "all"}
+            disabled={activeUpdate !== null}
+            onPress={() => runUpdateAll(true)}
+          />
+        ) : staleCount > 1 ? (
+          <Button
+            label={`Update all (${staleCount})`}
+            variant="primary"
+            icon="DownloadCloud"
+            loading={activeUpdate === "all"}
+            disabled={activeUpdate !== null}
+            onPress={() => runUpdateAll(false)}
+          />
+        ) : null}
+      </ScrollView>
+    </PluginThemeProvider>
+  );
+}
+
+export function PluginUpdatesPopover(props: PluginButtonContentProps) {
+  return (
+    <PluginThemeProvider theme={props.theme} layout={props.layout}>
+      <PluginUpdatesPopoverInner {...props} />
+    </PluginThemeProvider>
+  );
+}
+
+export function registerPluginUpdateHeaders(client: {
+  addHeaderButton(contribution: {
+    id: string;
+    workspaceId: string;
+    button: {
+      title: string;
+      icon: typeof PluginUpdatesIcon;
+      behavior: { kind: "popover"; Content: typeof PluginUpdatesPopover };
+    };
+  }): PluginButtonRegistration;
+  paseo: {
+    agents: {
+      list(): Promise<{
+        entries: Array<{ agent?: { workspaceId?: string | null } }>;
+      }>;
+      subscribe(listener: (update: { kind: string; agent?: { workspaceId?: string | null } }) => void): () => void;
+    };
+  };
+}) {
+  const registrations = new Map<string, PluginButtonRegistration>();
+  const add = (workspaceId: string) => {
+    if (!workspaceId || registrations.has(workspaceId)) return;
+    registrations.set(
+      workspaceId,
+      client.addHeaderButton({
+        id: "plugin-updates",
+        workspaceId,
+        button: {
+          title: "Plugin updates",
+          icon: PluginUpdatesIcon,
+          behavior: { kind: "popover", Content: PluginUpdatesPopover },
+        },
+      }),
+    );
+  };
+  const subscription = client.paseo.agents.subscribe((update) => {
+    if (update.kind === "upsert" && update.agent?.workspaceId) add(update.agent.workspaceId);
+  });
+  void client.paseo.agents.list().then((result) => {
+    for (const entry of result.entries) {
+      if (entry.agent?.workspaceId) add(entry.agent.workspaceId);
+    }
+  });
+  return () => {
+    subscription();
+    for (const registration of registrations.values()) registration.remove();
+    registrations.clear();
+  };
+}