paseo-smart-session 2.0.0 → 2.2.0

package/client/display.tsx

@@ -1,73 +1,96 @@
-import type { PluginClientContext, PluginSidebarContribution, PluginSurfaceProps } from "@getpaseo/plugin/client";
+import type { PluginClientContext, PluginSidebarItemProps, PluginSurfaceProps } from "@getpaseo/plugin/client";
 import { useSettings } from "@getpaseo/plugin/client";
-import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch } from "@getpaseo/plugin/client/ui";
+import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch, SidebarRow } from "@getpaseo/plugin/client/ui";
 import { useEffect } from "react";
 import { ActivityIndicator, ScrollView, Text, View } from "react-native";
 import { displayPreferences, displayRpc } from "../shared/display";
-import { withNavigation } from "./navigation";
+import { Chip, useNow } from "./kit";
+import { useLive, type Live } from "./live";
+import { OVERVIEW_SCREEN, sidebarTrailing } from "./overview";
 import { sidebarVisibility } from "./sidebar-visibility";
+import { tabular, toneColor } from "./theme";
 
 type Display = import("zod").infer<typeof displayPreferences.schema>;
 const listeners = new Set<(values: Display) => void>();
 export function subscribeDisplay(listener: (values: Display) => void) { listeners.add(listener); return () => { listeners.delete(listener); }; }
 
-function DisplaySettings({ theme }: PluginSurfaceProps) {
+/** Where Smart Session shows up. Hiding something never turns its feature off. */
+function DisplaySettings({ theme, layout }: PluginSurfaceProps) {
   const settings = useSettings(displayPreferences);
   const values = settings.status === "ready" ? settings.values : undefined;
   useEffect(() => {
     if (values !== undefined) for (const listener of listeners) listener(values);
   }, [values]);
 
-  if (settings.status === "loading") return <ActivityIndicator accessibilityLabel="Loading display settings" color={theme.colors.foregroundMuted} />;
+  if (settings.status === "loading") return <ActivityIndicator accessibilityLabel="Loading display settings" color={theme.colors.foregroundMuted} style={{ padding: 24 }} />;
   if (settings.status !== "ready") return (
-    <View style={{ gap: 12 }}>
+    <View style={{ gap: 12, padding: 16 }}>
       <Text style={{ color: theme.colors.statusDanger }}>{settings.error}</Text>
       <SettingsCard>
         <SettingsAction label="Try loading the saved settings again" actionLabel="Retry" onPress={() => void settings.reload()} />
         {settings.status === "invalid" && <SettingsAction label="Replace invalid display settings with defaults" actionLabel="Reset" disabled={settings.saving} onPress={() => void settings.reset()} />}
-
       </SettingsCard>
       {settings.saveError && <Text style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
     </View>
   );
 
   return (
-    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ padding: 16, gap: 16 }}>
-    <SettingsSection title="Navigation">
-      <SettingsCard>
-        <SettingsSwitch
-          label="Show in sidebar"
-          hint="Open this plugin from Command-K (Ctrl-K on Windows and Linux) while viewing a workspace or plugin on this host."
-          value={settings.values.showSidebar}
-          disabled={settings.saving}
-          onValueChange={(showSidebar) => void settings.save({ ...settings.values, showSidebar }, settings.revision)}
-        />
-
-        <SettingsSwitch label="Show composer button" hint="Command-K and the sidebar remain available when this button is hidden." value={settings.values.enable_composer_button} disabled={settings.saving} onValueChange={(enable_composer_button) => void settings.save({ ...settings.values, enable_composer_button }, settings.revision)} />
-      </SettingsCard>
-      {settings.saveError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
-    </SettingsSection>
+    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: 8, gap: 16 }}>
+      <SettingsSection title="Where Smart Session appears" info="Hiding a row or a pill never turns its feature off. ⌘K Smart Session still opens the overview.">
+        <SettingsCard>
+          <SettingsSwitch
+            label="Sidebar row"
+            hint="Smart Session in the sidebar, with the session window's usage, or how many sessions are paused."
+            value={settings.values.showSidebar}
+            disabled={settings.saving}
+            onValueChange={(showSidebar) => void settings.save({ ...settings.values, showSidebar }, settings.revision)}
+          />
+          <SettingsSwitch
+            label="Composer pills"
+            hint="The context ring and, while Session Guard runs, its shield, above each message box."
+            value={settings.values.enable_composer_button}
+            disabled={settings.saving}
+            onValueChange={(enable_composer_button) => void settings.save({ ...settings.values, enable_composer_button }, settings.revision)}
+          />
+        </SettingsCard>
+        {settings.saveError && <Text accessibilityRole="alert" style={{ color: theme.colors.statusDanger }}>{settings.saveError}</Text>}
+      </SettingsSection>
     </ScrollView>
   );
 }
 
-/** Settings notifications reach mounted screens; poll for changes made on other clients. */
-export function contributeDisplay(client: PluginClientContext, item: PluginSidebarContribution) {
-  const sidebar = sidebarVisibility(() => client.addSidebarItem(item));
+/** The sidebar row, the Display settings screen, and the preference poll that drives both. */
+export function contributeDisplay(client: PluginClientContext, live: Live) {
+  function SmartSessionSidebarItem({ currentScreen, openScreen, theme }: PluginSidebarItemProps) {
+    useLive(live);
+    const now = useNow(60_000);
+    const trailing = sidebarTrailing(live, now);
+    const c = theme.colors;
+    return (
+      <SidebarRow
+        icon="Gauge"
+        active={currentScreen?.screenId === OVERVIEW_SCREEN || currentScreen?.screenId === "paused-sessions"}
+        onPress={() => openScreen({ screenId: OVERVIEW_SCREEN })}
+        trailing={trailing === null ? undefined : trailing.tone === "muted"
+          ? <Text accessibilityLabel={`Session window ${trailing.label} used`} numberOfLines={1} style={{ color: c.foregroundMuted, fontSize: 12, lineHeight: 16, ...tabular }}>{trailing.label}</Text>
+          : <Chip theme={theme} label={trailing.label} color={toneColor(c, trailing.tone)} />}
+      />
+    );
+  }
+
+  const sidebar = sidebarVisibility(() => client.addSidebarHeaderItem({ id: "smart-session", title: "Smart Session", Component: SmartSessionSidebarItem }));
   // Paseo 0.10.1 memoizes sidebar route resolution when an installation mounts.
   // Register synchronously, then reconcile the saved preference, so that an
-  // already-open sidebar route can resolve its surface during that first render.
+  // already-open sidebar route can resolve its screen during that first render.
   sidebar.set(true);
-  const Settings = withNavigation(DisplaySettings, client, item.surface, "display");
-  const removeSurface = client.addSurface("display-settings", Settings);
-  const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: Settings });
+  const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: DisplaySettings });
   const removeCommand = client.addCommandCenterItem({
     id: "display-settings",
-    title: `${item.title}: display settings`,
+    title: "Smart Session: display settings",
     icon: "PanelLeft",
-    keywords: [item.title, "sidebar", "show", "hide", "display", "settings"],
+    keywords: ["smart session", "sidebar", "pill", "show", "hide", "display", "settings"],
     context: "global",
-    onSelect({ openSurface }) { openSurface("display-settings"); },
+    onSelect({ openSettings }) { openSettings("display"); },
   });
   let disposed = false;
   let pending = false;
@@ -95,7 +118,6 @@ export function contributeDisplay(client: PluginClientContext, item: PluginSideb
     clearInterval(timer);
     listeners.delete(update);
     sidebar.dispose();
-    removeSurface();
     removeSettings();
     removeCommand();
   };

package/client/guard/index.tsx

@@ -0,0 +1,48 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+import { ScrollView } from "react-native";
+
+import { TimelineDataSchema } from "../../shared/guard/timeline.ts";
+import type { AgentDirectory } from "../agents.ts";
+import type { Live } from "../live.ts";
+import { PausedSessions } from "./paused.tsx";
+import { guardPillIcons } from "./pill-icons.tsx";
+import { contributePills } from "./pills.ts";
+import { GuardSettings } from "./settings.tsx";
+import { GUARD_SCREENS, GUARD_SETTINGS } from "./surfaces.ts";
+import { GuardTimelineItem } from "./timeline.tsx";
+
+/** Session Guard's client half: its settings, paused-sessions screen, timeline cards and pill. */
+export function contributeGuardClient(client: PluginClientContext, agents: AgentDirectory, live?: Live) {
+  const openPaused = () => client.openScreen({ screenId: GUARD_SCREENS.paused });
+  const openSettings = () => client.openSettings(GUARD_SETTINGS);
+  const Settings = (props: Parameters<typeof GuardSettings>[0] extends infer P ? Omit<P, "openOverview"> : never) => (
+    <ScrollView style={{ flex: 1 }} contentContainerStyle={{ paddingVertical: 8 }}>
+      <GuardSettings {...props} openOverview={openPaused} />
+    </ScrollView>
+  );
+
+  const removers = [
+    client.addScreen({ id: GUARD_SCREENS.paused, title: "Paused sessions", Component: (props) => <PausedSessions {...props} openSettings={openSettings} /> }),
+    client.addSettingsScreen({ id: GUARD_SETTINGS, title: "Session Guard", icon: "ShieldCheck", Component: Settings }),
+    client.addCommandCenterItem({
+      id: "session-guard-settings", title: "Session Guard: settings", icon: "ShieldCheck",
+      keywords: ["quota", "limit", "reset", "pause", "resume", "protection", "session guard"], context: "global",
+      onSelect({ openSettings: open }) { open(GUARD_SETTINGS); },
+    }),
+    client.addCommandCenterItem({
+      id: "session-guard-paused", title: "Session Guard: paused sessions", icon: "Pause",
+      keywords: ["quota", "waiting", "reset", "resume", "subagents", "session guard"], context: "global",
+      onSelect({ openScreen }) { openScreen({ screenId: GUARD_SCREENS.paused }); },
+    }),
+    // The kind and version the standalone plugin wrote, so a pause it recorded and this
+    // plugin later delivers renders the same card.
+    client.addTimelineRenderer({
+      kind: "quota-pause", version: 1, schema: TimelineDataSchema,
+      Component: (props) => <GuardTimelineItem {...props} openOverview={openPaused} />,
+    }),
+    contributePills(client, agents, guardPillIcons, live),
+  ];
+  return () => {
+    for (const remove of removers.splice(0)) remove();
+  };
+}

package/client/guard/paused.tsx

@@ -0,0 +1,164 @@
+import { useEffect, useRef, useState } from "react";
+import { Text, TextInput, View } from "react-native";
+import { type PluginSurfaceProps, useRpc } from "@getpaseo/plugin/client";
+import { Icon, ScrollView, useToast } from "@getpaseo/plugin/client/ui";
+import { cancelResumeRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { governorNotice, pauseOwnerNote, pausedSessions, pausePresentation } from "../../shared/guard/presentation.ts";
+import { timestamp, type Pause } from "../../shared/guard/policy.ts";
+import { formatDuration, formatRelative } from "../../shared/format.ts";
+import { formatMoment } from "../../shared/forecast.ts";
+import { Button, Card, CardRow, Chip, IconButton, SectionHead, text, useNow } from "../kit.tsx";
+import { Skeleton } from "../motion.tsx";
+import { tabular } from "../theme.ts";
+
+const providerName = (id: string) => (id === "claude" ? "Claude" : id === "codex" ? "Codex" : id);
+
+/**
+ * Every Session Guard pause on this host, as times: when each session's window
+ * resets and whether it continues by itself. Rows act only on pauses this process
+ * governs; another governor's pauses are listed read-only.
+ */
+export function PausedSessions({ theme, host, layout, navigation, openSettings }: PluginSurfaceProps & { openSettings(): void }) {
+  const c = theme.colors;
+  const t = text(c);
+  const compact = layout.compact;
+  const toast = useToast();
+  const now = useNow(15_000);
+  const read = useRpc(statusRpc);
+  const cancel = useRpc(cancelResumeRpc);
+  const [status, setStatus] = useState<Awaited<ReturnType<typeof read>> | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+  const refresh = useRef<() => Promise<void>>(async () => {});
+  useEffect(() => {
+    let stopped = false, fetching = false;
+    const fetch = async () => {
+      if (fetching || stopped) return;
+      fetching = true;
+      try { const next = await read({}); if (!stopped) { setStatus(next); setLoadError(null); } }
+      catch { if (!stopped) setLoadError("Couldn't refresh paused sessions. Showing the last report; retrying."); }
+      finally { fetching = false; }
+    };
+    refresh.current = fetch;
+    void fetch(); const timer = setInterval(() => void fetch(), 5000);
+    return () => { stopped = true; clearInterval(timer); };
+  }, [read]);
+  const release = async (pause: Pause) => {
+    if (busy) return;
+    setBusy(pause.agentId);
+    try { await cancel({ agentId: pause.agentId }); await refresh.current(); toast.show(pause.suspension ? "Released · protection off for that session" : "Continuation cancelled"); }
+    catch { toast.error("Couldn't change this pause. Refresh and try again."); }
+    finally { setBusy(null); }
+  };
+
+  const all = status ? pausedSessions(status.pauses) : [];
+  const visible = status ? pausedSessions(status.pauses, query) : [];
+  const attention = visible.filter((p) => p.phase === "attention");
+  const waiting = visible.filter((p) => p.phase !== "attention");
+  // Both plugins share one state file: when this one is not governing, the list is
+  // the other plugin's (or a leftover), and its controls would only fail.
+  const notice = status ? governorNotice(status) : null;
+  const owner = status ? pauseOwnerNote(status) : null;
+  const autoResume = status ? status.policy.enabled && status.policy.autoResume : false;
+
+  // The headline is the moment: when they come back, or that one needs a look.
+  const allWaiting = all.filter((p) => p.phase !== "attention");
+  const allStuck = all.length - allWaiting.length;
+  const resets = allWaiting.map((p) => timestamp(p.anchorResetsAt)).filter((v): v is number => v !== null && v > now).sort((a, b) => a - b);
+  const shared = resets.length === allWaiting.length && resets.length > 0 && resets[resets.length - 1]! - resets[0]! < 60_000 ? resets[0]! : null;
+  const n = (count: number, one: string, many: string) => `${count} ${count === 1 ? one : many}`;
+  const clock = (ms: number) => formatMoment(new Date(ms).toISOString(), now);
+  const title = status === null ? null
+    : all.length === 0 ? "Nothing is paused"
+      : allWaiting.length === 0 ? `${n(allStuck, "session needs", "sessions need")} a look`
+        : shared !== null ? (autoResume ? `${n(allWaiting.length, "session resumes", "sessions resume")} at ${clock(shared)}` : `${n(allWaiting.length, "session waits", "sessions wait")} for the ${clock(shared)} reset`)
+          : resets.length > 0 ? `${n(allWaiting.length, "session", "sessions")} paused · next ${autoResume ? "resumes" : "reset"} at ${clock(resets[0]!)}`
+            : `${n(allWaiting.length, "session waits", "sessions wait")} for a fresh reading`;
+  const sentence = status === null ? "" : [
+    shared !== null ? `in ${formatDuration(shared - now)}` : null,
+    allStuck > 0 && allWaiting.length > 0 ? `${allStuck} ${allStuck === 1 ? "needs" : "need"} a look` : null,
+    all.length === 0 || allWaiting.length === 0 ? null : owner ? "Managed by another Session Guard" : autoResume ? "Each continues in the same conversation" : "Continue each by hand after the reset",
+    status.checkedAt ? `Checked ${formatRelative(status.checkedAt, now)}` : "Waiting for the first usage check",
+  ].filter(Boolean).join(" · ");
+
+  const row = (pause: Pause, i: number) => {
+    const presentation = pausePresentation(pause, status!.policy, now);
+    const reset = timestamp(pause.anchorResetsAt);
+    const stuck = pause.phase === "attention";
+    // A row leads with what differs between rows, the session; its time only when it differs from the headline's.
+    const ownTime = !stuck && !pause.demo && reset !== null && reset > now && (shared === null || Math.abs(reset - shared) >= 60_000) ? formatMoment(pause.anchorResetsAt!, now) : null;
+    const after = stuck ? (pause.note ?? "It stopped before Session Guard could confirm the pause. Check it before continuing by hand.")
+      : pause.demo ? "Test pause · waits for you"
+        : reset === null ? "Waiting for the provider to report the reset"
+          : reset > now ? `${autoResume ? "Resumes" : "Resets"} in ${formatDuration(reset - now)}`
+            : `Reset was ${formatMoment(pause.anchorResetsAt!, now)} · waiting for a fresh reading`;
+    const chips = [providerName(pause.provider), presentation.coverage];
+    const canAct = owner === null;
+    return <CardRow key={pause.id} theme={theme} first={i === 0} style={{ gap: 6 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+        <Icon name={stuck ? "TriangleAlert" : "Pause"} size={14} color={stuck ? c.statusDanger : c.statusWarning} />
+        <Text numberOfLines={2} style={{ ...t.title, flex: 1 }}>{presentation.title}</Text>
+        {ownTime ? <Text style={{ color: c.foreground, fontSize: 15, lineHeight: 21, fontWeight: "600", ...tabular }}>{ownTime}</Text> : null}
+      </View>
+      <Text style={{ ...t.meta, color: stuck ? c.statusDanger : c.foregroundMuted, paddingLeft: 22 }}>{after}</Text>
+      <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 6, paddingLeft: 22 }}>
+        {chips.map((chip) => <Chip key={chip} theme={theme} label={chip} />)}
+        {owner ? <Chip theme={theme} label="Read-only here" /> : null}
+      </View>
+      {owner ? <Text style={{ ...t.meta, paddingLeft: 22 }}>{owner}</Text> : null}
+      <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 6, marginTop: 2, paddingLeft: 22 }}>
+        {navigation ? <Button theme={theme} small compact={compact} icon={compact ? undefined : "ArrowUpRight"} title="Open session" onPress={() => navigation.openAgent({ agentId: pause.agentId, serverId: host.id })} /> : null}
+        <View style={{ flex: 1, minWidth: 8 }} />
+        {canAct ? <Button theme={theme} small compact={compact} kind="ghost" title={busy === pause.agentId ? "Updating…" : presentation.actionLabel} disabled={busy !== null}
+          accessibilityHint={presentation.actionHint} onPress={() => void release(pause)} /> : null}
+      </View>
+    </CardRow>;
+  };
+
+  return <ScrollView contentContainerStyle={{ padding: compact ? 16 : 32, paddingBottom: 48 }}>
+    <View style={{ width: "100%", maxWidth: 760, alignSelf: "center", gap: compact ? 18 : 22 }}>
+      <View style={{ gap: 6 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+          {title ? <Text accessibilityRole="header" style={{ flex: 1, color: c.foreground, fontSize: compact ? 19 : 22, lineHeight: compact ? 25 : 29, fontWeight: "600" }}>{title}</Text>
+            : <View style={{ flex: 1 }}><Skeleton width="40%" height={22} color={c.surface2} /></View>}
+          <IconButton theme={theme} icon="Settings" label="Session Guard settings" compact={compact} onPress={openSettings} />
+        </View>
+        {sentence ? <Text style={{ ...t.meta, fontSize: 13, lineHeight: 19 }}>{sentence}</Text> : null}
+      </View>
+
+      {notice ? <Card theme={theme}><CardRow theme={theme} first style={{ flexDirection: "row", gap: 10, alignItems: "flex-start" }}>
+        <Icon name="ShieldOff" size={15} color={c.foregroundMuted} />
+        <View style={{ flex: 1, gap: 3 }}>
+          <Text style={t.label}>{notice.title}</Text>
+          <Text style={t.meta}>{notice.hint}</Text>
+        </View>
+        <Button theme={theme} small compact={compact} title="Settings" onPress={openSettings} />
+      </CardRow></Card> : null}
+
+      {all.length > 5 || query !== "" ? <TextInput value={query} onChangeText={setQuery} placeholder="Find a paused session by title or provider" placeholderTextColor={c.foregroundMuted} accessibilityLabel="Find a paused session"
+        style={{ minHeight: compact ? 44 : 34, paddingHorizontal: 12, borderRadius: 8, borderWidth: 1, borderColor: c.border, backgroundColor: c.surface1, color: c.foreground, fontSize: 13 }} /> : null}
+
+      {status === null && !loadError ? <Card theme={theme}>{[0, 1].map((i) => <CardRow key={i} theme={theme} first={i === 0} style={{ gap: 8 }}>
+        <Skeleton width="30%" height={14} color={c.surface2} /><Skeleton width="70%" height={11} color={c.surface2} /></CardRow>)}</Card> : null}
+
+      {status && all.length === 0 && !notice ? <Card theme={theme}><CardRow theme={theme} first style={{ gap: 6, paddingVertical: 16 }}>
+        <Text style={t.label}>Nothing is waiting for a reset</Text>
+        <Text style={t.meta}>{`When a protected session reaches ${status.policy.thresholdPct}% of its session window, Session Guard pauses it here and ${status.policy.autoResume ? "continues it in the same conversation after the reset" : "you continue it after the reset"}.`}</Text>
+      </CardRow></Card> : null}
+      {status && all.length > 0 && visible.length === 0 ? <Text style={t.meta}>No paused session matches that.</Text> : null}
+
+      {attention.length > 0 ? <View style={{ gap: 8 }}>
+        <SectionHead theme={theme} title="Needs attention" count={attention.length} />
+        <Card theme={theme}>{attention.map(row)}</Card>
+      </View> : null}
+      {waiting.length > 0 ? <View style={{ gap: 8 }}>
+        <SectionHead theme={theme} title="Waiting for the reset" count={waiting.length} />
+        <Card theme={theme}>{waiting.map(row)}</Card>
+      </View> : null}
+
+      {loadError ? <Text accessibilityRole="alert" style={{ ...t.meta, color: c.statusDanger }}>{status ? loadError : "Couldn't load paused sessions. Retrying."}</Text> : null}
+      {status?.error && !notice ? <Text accessibilityRole="alert" style={{ ...t.meta, color: c.statusDanger }}>{status.error}</Text> : null}
+    </View>
+  </ScrollView>;
+}

package/client/guard/pill-icons.tsx

@@ -0,0 +1,26 @@
+import type { PluginButtonIcon, PluginButtonIconProps } from "@getpaseo/plugin/client";
+import { Icon } from "@getpaseo/plugin/client/react-native";
+
+// Like Smart Compact, keep the host's pill chrome and color the icon slot.
+function GuardOnIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldCheck" size={size} color={theme.colors.foreground} />;
+}
+
+function GuardOffIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="ShieldOff" size={size} color={theme.colors.foregroundMuted} />;
+}
+
+function GuardPausedIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="Pause" size={size} color={theme.colors.statusWarning} />;
+}
+
+function GuardAttentionIcon({ theme, size }: PluginButtonIconProps) {
+  return <Icon name="TriangleAlert" size={size} color={theme.colors.statusDanger} />;
+}
+
+export const guardPillIcons: Readonly<Record<string, PluginButtonIcon>> = {
+  ShieldCheck: GuardOnIcon,
+  ShieldOff: GuardOffIcon,
+  Pause: GuardPausedIcon,
+  TriangleAlert: GuardAttentionIcon,
+};

package/client/guard/pills.ts

@@ -0,0 +1,132 @@
+/**
+ * The Session Guard pill: one per live session, beside Smart Compact's.
+ *
+ * Drawn only while this plugin is the host's Session Guard governor. Off, there is
+ * nothing for it to say; deferring to the standalone plugin, that plugin draws its own,
+ * and two shields on one composer would contradict each other. While the feature is
+ * being turned off, a session that still has a pause keeps its pill so the pause can
+ * be released from where it is.
+ */
+import type { PluginButtonIcon, PluginClientContext } from "@getpaseo/plugin/client";
+import type { AgentDirectory } from "../agents.ts";
+import { GUARD_SCREENS, GUARD_SETTINGS } from "./surfaces.ts";
+import type { Live } from "../live.ts";
+import { cancelResumeRpc, setProtectionRpc, statusRpc } from "../../shared/guard/contracts.ts";
+import { isPending, protects, type Pause, type Policy } from "../../shared/guard/policy.ts";
+
+export function pillPresentation(policy: Policy, enabled: boolean, pause: Pause | undefined) {
+  if (!policy.enabled) return { label: "Guard off", title: "Session Guard is disabled on this host", icon: "ShieldOff" };
+  if (!enabled) return { label: "Guard off", title: "This session is excluded from automatic quota protection", icon: "ShieldOff" };
+  if (pause?.phase === "attention") return { label: "Check session", title: pause.note ?? "Check this session before continuing", icon: "TriangleAlert" };
+  if (pause) {
+    if (pause.demo) return { label: "Paused · demo", title: "This test session is paused. Try Resume now in its timeline; no provider quota was changed.", icon: "Pause" };
+    const date = pause.anchorResetsAt ? new Date(pause.anchorResetsAt) : null;
+    const time = date && Number.isFinite(date.getTime()) ? date.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" }) : null;
+    const resetDetail = date ? ` Expected reset ${date.toLocaleString([], { dateStyle: "short", timeStyle: "short" })}.` : " Reset time is not available yet.";
+    const due = date !== null && Number.isFinite(date.getTime()) && date.getTime() <= Date.now();
+    return { label: due ? "Paused · reset due" : time ? `Paused · ${time}` : "Paused · awaiting reset", title: (policy.autoResume
+      ? `Paused at the session limit${pause.suspension ? ", including native subagents" : ""}. Automatic continuation is scheduled after reset.`
+      : pause.suspension ? "Session and native subagents are paused. Release and turn off to continue manually; automatic continuation is off."
+      : "Paused at the session limit. Continue manually after reset; automatic continuation is off.") + resetDetail, icon: "Pause" };
+  }
+  return { label: "Session Guard", title: policy.autoResume
+    ? `Pause at ${policy.thresholdPct}% session usage and continue after reset`
+    : `Pause at ${policy.thresholdPct}% session usage; continue manually after reset`, icon: "ShieldCheck" };
+}
+
+/** How often a client re-reads Session Guard status while it is on, and while it is off. */
+const ACTIVE_POLL_MS = 5_000;
+const IDLE_POLL_MS = 60_000;
+
+const wakers = new Set<() => void>();
+/**
+ * Re-reads status now. The settings screens call it whenever the Session Guard
+ * document changes — their `useSettings` hears changes from every client — so pills
+ * follow a switch without polling hard while the feature is off.
+ */
+export function refreshGuardPills(): void {
+  for (const wake of [...wakers]) wake();
+}
+
+export function contributePills(client: PluginClientContext, agents: AgentDirectory, icons: Readonly<Record<string, PluginButtonIcon>> = {}, live?: Live) {
+  let stopped = false;
+  let running = false;
+  let status: Awaited<ReturnType<typeof readStatus>> | null = null;
+  const handles = new Map<string, { workspaceId: string; signature: string; registration: ReturnType<PluginClientContext["addComposerPill"]> }>();
+  const readStatus = () => client.rpc(statusRpc, {});
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const refresh = async () => {
+    if (stopped || running) return;
+    running = true;
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+    try {
+      const next = await readStatus();
+      if (!stopped) {
+        status = next; reconcile();
+        // The sidebar row counts pauses only this process can act on.
+        const pending = next.governor === "active" ? next.pauses.filter(isPending) : [];
+        live?.setPaused({ waiting: pending.filter(p => p.phase !== "attention").length, attention: pending.filter(p => p.phase === "attention").length });
+      }
+    }
+    catch { /* Keep the last confirmed presentation across a brief disconnect. */ }
+    finally {
+      running = false;
+      // Off here and nobody governing from here: nothing to draw, so check rarely.
+      const idle = status !== null && !status.policy.enabled && status.governor === "off";
+      if (!stopped) timer = setTimeout(() => void refresh(), idle ? IDLE_POLL_MS : ACTIVE_POLL_MS);
+    }
+  };
+  function reconcile() {
+    if (stopped || !status) return;
+    const sessions = new Map<string, string>();
+    if (status.governor === "active") {
+      for (const [agentId, agent] of agents.current()) {
+        if (agent.closed) continue;
+        if (status.policy.enabled || status.pauses.some(p => p.agentId === agentId && isPending(p))) sessions.set(agentId, agent.workspaceId);
+      }
+    }
+    for (const [id, handle] of handles) {
+      if (sessions.get(id) !== handle.workspaceId) { handle.registration.remove(); handles.delete(id); }
+    }
+    for (const [agentId, workspaceId] of sessions) {
+      const enabled = protects(status.policy, status.overrides, agentId);
+      const pause = status.pauses.find(p => p.agentId === agentId && isPending(p));
+      const presentation = pillPresentation(status.policy, enabled, pause);
+      const signature = JSON.stringify([presentation, enabled, agentId in status.overrides, pause?.id]);
+      const handle = handles.get(agentId);
+      // Preserve the host menu while polling or receiving agent updates.
+      // Replacing behavior on every read remounts an open adaptive menu.
+      if (handle?.signature === signature) continue;
+      const button = {
+        ...presentation,
+        icon: icons[presentation.icon] ?? presentation.icon,
+        behavior: { kind: "menu" as const, items: [
+          { kind: "item" as const, id: "toggle", title: enabled ? "Turn off for this session" : "Protect this session", icon: enabled ? "ShieldOff" : "ShieldCheck",
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(setProtectionRpc, { agentId, enabled: !enabled }); await refresh(); } } },
+          { kind: "item" as const, id: "default", title: "Use host default", visible: agentId in status.overrides,
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(setProtectionRpc, { agentId, enabled: null }); await refresh(); } } },
+          { kind: "item" as const, id: "cancel", title: pause?.suspension ? "Release and turn off for this session" : "Cancel automatic continuation", visible: !!pause,
+            behavior: { kind: "action" as const, onPress: async () => { await client.rpc(cancelResumeRpc, { agentId }); await refresh(); } } },
+          { kind: "separator" as const, id: "separator" },
+          { kind: "item" as const, id: "paused-sessions", title: "All paused sessions", icon: "Pause",
+            behavior: { kind: "action" as const, onPress: () => { client.openScreen({ screenId: GUARD_SCREENS.paused }); } } },
+          { kind: "item" as const, id: "settings", title: "Session Guard settings", icon: "Settings",
+            behavior: { kind: "action" as const, onPress: () => { client.openSettings(GUARD_SETTINGS); } } },
+        ] },
+      };
+      if (handle) { handle.registration.update(button); handle.signature = signature; }
+      else handles.set(agentId, { workspaceId, signature, registration: client.addComposerPill({ id: "session-guard", workspaceId, agentId, button }) });
+    }
+  }
+  const unsubscribe = agents.subscribe(reconcile);
+  const wake = () => void refresh();
+  wakers.add(wake);
+  void refresh();
+  return () => {
+    stopped = true; wakers.delete(wake); unsubscribe();
+    if (timer !== null) clearTimeout(timer);
+    for (const handle of handles.values()) handle.registration.remove();
+    handles.clear();
+  };
+}