paseo-smart-session 3.0.0 → 3.2.0

package/README.md

@@ -5,7 +5,7 @@
 [![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.14.0-8A63D2?style=for-the-badge)](https://paseo.sh)
 [![License](https://img.shields.io/github/license/tomgrin10/paseo-smart-session?style=for-the-badge&color=2563eb)](LICENSE)
 
-Know when your plan runs out, and let agents manage their own long-running work. Smart Session records your Claude plan usage and turns it into a forecast ("Session runs out around 5:40 PM"), shows how full each session's context is, lets an agent save its task state and compact itself at a safe point, and with Session Guard pauses work at the session limit and continues it after the reset.
+Know when your plan runs out, and let agents manage their own long-running work. Smart Session records your Claude plan usage and turns it into a forecast ("Session runs out around 5:40 PM"), shows how full each session's context is, lets an agent save its task state and compact itself at a safe point, and pauses work at the session limit to continue it after the reset.
 
 <picture>
   <source media="(prefers-color-scheme: light)" srcset="docs/media/smart-session-hero-light.png">
@@ -24,18 +24,18 @@ On first load it registers its Claude Code hooks, touching only entries that poi
 
 ## Use
 
-**Smart Session** in the sidebar opens the overview. Its headline says when the session window runs out at the current pace, or that it lasts until the reset.
+**Smart Session** in the sidebar opens the overview. Its headline says when the session window runs out at the current pace, or that it lasts until the reset. While sessions are paused at the limit it leads with them instead ("2 sessions resume at 5:58 PM"), and lists them first with their actions.
 
 - **Plan limits.** Each window (the 5-hour session, the week, per-model weekly caps) shows how much is used, when it resets, and where it lands at the current pace: a faint extension of the meter, and a tick where an even pace would be. The session window adds a chart of its recorded usage and the projection to the reset, plus every session window of the last 14 days, so you can see how often you hit the limit.
 - **Session context.** Every open session with its share of the context window, the line where Smart Compact asks it to compact, how fast it is filling, and whether it is enrolled. Press a row to open the session.
-- **Smart Compact and Session Guard.** One switch each, what they will do, and links to their settings.
+- **Smart Compact and Pause at the limit.** One switch each, what they will do next, and the sessions you changed from your default.
 - **Tokens, last 30 days.** Billable tokens, the cache hit rate and the subagent share, per day, by hour of the week, by workspace and by model, reconstructed from Claude Code's transcripts.
 
-The pill above each message box is a ring of that session's context, with a tick at its compact line. Press it to see the detail, when it last saved its task state and compacted, and to enrol the session or take it out.
+Each session has one pill above its message box: a ring of its context, with a tick at its compact line. Press it to see the detail, when it last saved its task state and compacted, and to switch Smart Compact and Pause at the limit for that session. When the session is paused at the limit the same pill turns amber and says when it resumes, and it stays up even if you hide the pill.
 
 ![Pressing the context ring above the message box, then following it to the Smart Session screen and sweeping the window chart: recorded usage up to now, the projection at this pace, and the stretch after it runs out](docs/media/smart-session-flow.gif)
 
-![A session's context popover: 34% of a 1M context, 336k tokens, compacts at 30%, past its compact line; task state saved 10m ago; last compaction 3h ago, 318k to 31k; the Smart Compact switch for this session](docs/media/smart-session-pill.png)
+![Two popovers of the one pill. Left: 34% of a 1M context, past its compact line, task state and last compaction, then the Smart Compact and Pause at the limit switches for this session. Right: the same pill while paused, reading Resumes 6:27 AM, with Cancel continuation and a link to all paused sessions](docs/media/smart-session-pill.png)
 
 Agents get these tools:
 
@@ -45,7 +45,7 @@ Agents get these tools:
 | `checkpoint` | Save durable task state for this session |
 | `request_compaction` | Queue `/compact`, and choose whether and how to continue afterwards |
 | `defer_compaction` | Put off a compaction and record why |
-| `budget_status` | Plan usage, burn rate and reset times, and whether Session Guard will pause this session |
+| `budget_status` | Plan usage, burn rate and reset times, and whether this session pauses at the limit |
 
 The usual flow is `context_status → checkpoint → request_compaction`, then stop or re-read the state and continue. Saved state holds the goal, current step, decisions made and approaches that failed, so a resumed agent neither redoes work nor asks how to continue. In the chat each call is one line ("Saved task state · Cap retries at five", "Asked to compact · …"), and the messages Smart Session sends show as small cards with the full text one press away.
 
@@ -59,32 +59,43 @@ After compaction, the agent chooses to stop (`continue_after_compaction: false`)
 
 The forecast uses the last half hour for the session window and the window's own average for a week, so a burst of work doesn't read as "the week runs out tonight".
 
-**Settings → Plugins → Smart Session → Smart Compact:**
+## Pause at the limit
 
-| Setting | Default | |
-| --- | --- | --- |
-| Smart Compact | On | Context notices and agent-requested compaction |
-| Enrol sessions automatically | On | Enrol a session once it writes task state |
-| Context pill on every session | On | The ring above each message box |
-| Windows of 400k or more | 30% | Where large windows are asked to compact |
-| Smaller windows | 85% | Where smaller windows are asked to compact |
-| Register the hooks | On | Keep the context and compaction hooks installed in Claude Code |
+When the provider's session window is spent, Smart Session pauses running sessions instead of letting them fail, and continues the same conversations once the window resets, even with the app closed. It is **off by default**: turn it on from the overview or in settings. It was the standalone [Session Guard](https://github.com/tomgrin10/paseo-session-guard) plugin, and its per-session choices and waiting pauses carry over.
 
-## Session Guard
+On Linux, Claude and Codex sessions pause in place together with their native subagents; elsewhere the turn is interrupted and one continuation is sent after the reset. A paused session's pill, its chat and its workspace say so: the chat gets a card with the time it resumes, **Resume now** and **Dismiss pause**, which folds into one line once the pause ends. For Claude, a reset is confirmed from whichever is fresher, Paseo's cached usage or Smart Session's own recorder.
 
-Session Guard pauses agents at the provider's session limit and continues the same conversations after the reset, even with the app closed. It is the [Session Guard](https://github.com/tomgrin10/paseo-session-guard) plugin folded into Smart Session, and it is **off by default**: turn it on from the overview or **Settings → Plugins → Smart Session → Session Guard**.
+![A pause card in the chat with the time it resumes, Resume now and Dismiss pause, and the Smart Session screen leading with 2 sessions resume at 6:27 AM above the list of paused sessions](docs/media/smart-session-guard.png)
 
-On Linux, Claude and Codex sessions pause in place together with their native subagents; elsewhere the turn is interrupted and one continuation is sent after the reset. Each paused session gets a card in its chat with the reset time and a countdown, **Resume now** and **Dismiss pause**; once the pause ends the card folds into one line. **Paused sessions** lists every pause by its reset time, and the session's pill and its workspace read **Paused**. For Claude, a reset is confirmed from whichever is fresher, Paseo's cached usage or Smart Session's own recorder.
+If the standalone Session Guard plugin is still enabled, it keeps doing the pausing and Smart Session says so in one line, so a session is never paused twice. Disable or uninstall it to hand over. See the [guide](docs/session-guard.md) for timing and limits.
 
-![Session Guard: a pause card in the chat with the reset time, Resume now and Dismiss pause, and the Paused sessions screen listing sessions waiting for the reset](docs/media/smart-session-guard.png)
+On a phone, the pill opens as a sheet and every screen fits one column.
 
-While the standalone plugin is enabled, Smart Session leaves session protection to it, so a session is never paused twice. Disable or uninstall Session Guard to hand over; per-session choices and waiting pauses in `$PASEO_HOME/plugin-data/session-guard/` carry over. See the [Session Guard guide](docs/session-guard.md) for settings and limits.
+![Smart Session at phone width: the overview leading with paused sessions, the pill's sheet while paused, and the settings screen](docs/media/smart-session-mobile.png)
 
-On a phone, the pill popovers open as sheets and every screen fits one column.
+## Settings
 
-![Smart Session at phone width: the overview, the context popover as a sheet, and Paused sessions](docs/media/smart-session-mobile.png)
+Everything is on one screen, **Settings → Plugins → Smart Session**, in the order a session meets it. ⌘K **Smart Session: settings** opens it.
 
-**Settings → Plugins → Smart Session → Display** hides the sidebar row or the composer pills; neither turns a feature off.
+| Section | Setting | Default | |
+| --- | --- | --- | --- |
+| Smart Compact | Smart Compact | On | Context notices and agent-requested compaction |
+| | Enrol sessions automatically | On | Enrol a session once it writes task state |
+| When to ask | Windows of 400k or more | 30% | Where large windows are asked to compact |
+| | Smaller windows | 85% | Where smaller windows are asked to compact |
+| Pause at the limit | Pause at the limit | Off | Pause sessions at the session limit |
+| | Sessions | Every session | Or only the ones you turn on from their pill |
+| | Continue after the reset | On | Off, you continue each one by hand |
+| | Include native subagents | On | Freeze nested workers too (Linux) |
+| | Label paused workspaces | On | An amber Paused label in the sidebar |
+| Display | Sidebar row | On | |
+| | Pill on every session | On | A paused session keeps its pill either way |
+| Claude Code | Register the hooks | On | Keep the context and compaction hooks installed |
+| Limit timing | Pause at, check interval, wait after reset, spacing, continuation message, providers, windows | 100%, 15s, 30s, 5s | Behind **Edit**; each field is checked on its own |
+
+Hiding the row or the pill never turns a feature off.
+
+![The Smart Session settings screen: Smart Compact, When to ask, Pause at the limit, Display, Claude Code and Limit timing](docs/media/smart-session-settings.png)
 
 ## Data and access
 

package/client/chat.tsx

@@ -52,7 +52,7 @@ function ToolRowView({ item, theme }: PluginTimelineItemProps<ToolRow>) {
 const CARD: Record<PromptCard["kind"], { icon: string; title: string }> = {
   compact: { icon: "FoldVertical", title: "Compaction the agent asked for" },
   continue: { icon: "CornerDownRight", title: "Continue after compaction" },
-  "guard-continue": { icon: "ShieldCheck", title: "Continue after the reset" },
+  "guard-continue": { icon: "Play", title: "Continue after the reset" },
   "guard-resume": { icon: "Play", title: "Resume now" },
 };
 
@@ -71,7 +71,7 @@ function PromptCardView({ item, theme, layout }: PluginTimelineItemProps<PromptC
   const card = item.data;
   const [expanded, setExpanded] = useState(false);
   const look = CARD[card.kind];
-  const sender = card.kind.startsWith("guard") ? "Session Guard" : "Smart Compact";
+  const sender = card.kind.startsWith("guard") ? "Smart Session" : "Smart Compact";
   return <View style={{ alignSelf: layout.compact ? "stretch" : "flex-end", width: "100%", maxWidth: 560, marginVertical: 4 }}>
     <View style={[{ borderRadius: 12, backgroundColor: c.surface1, overflow: "hidden" }, raised(c)]}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 8, paddingHorizontal: 14, paddingTop: 11, paddingBottom: 4 }}>

package/client/commands.ts

@@ -0,0 +1,62 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+
+type CommandItem = Parameters<PluginClientContext["addCommandCenterItem"]>[0];
+
+import { displayPreferences, displayRpc } from "../shared/display.ts";
+import { enrolmentState } from "../shared/governor.ts";
+import { getSettings, setSettings } from "../shared/smart-session.ts";
+import { refreshPills } from "./pill-store.ts";
+import { OVERVIEW_SCREEN, SETTINGS_SCREEN } from "./screens.ts";
+
+/**
+ * Smart Session in the Command Center: one name, four places. The old Session Guard
+ * and display items folded in here; their keywords stay so muscle memory still finds them.
+ */
+export function commandItems(): CommandItem[] {
+  return [
+    {
+      id: "smart-session-open",
+      title: "Smart Session",
+      icon: "Gauge",
+      keywords: ["usage", "budget", "limit", "forecast", "context", "tokens", "compact", "smart session", "overview", "plan"],
+      context: "global",
+      onSelect({ openScreen }) { openScreen({ screenId: OVERVIEW_SCREEN }); },
+    },
+    {
+      id: "smart-session-settings",
+      title: "Smart Session: settings",
+      icon: "Settings",
+      keywords: ["settings", "smart compact", "threshold", "hooks", "pause at the limit", "protection", "quota", "limit", "guard", "session guard", "display", "sidebar", "pill"],
+      context: "global",
+      onSelect({ openSettings }) { openSettings(SETTINGS_SCREEN); },
+    },
+    {
+      id: "smart-session-paused",
+      title: "Smart Session: paused sessions",
+      icon: "Pause",
+      keywords: ["paused", "pause", "resume", "waiting", "reset", "quota", "limit", "subagents", "guard", "session guard"],
+      context: "global",
+      onSelect({ openScreen }) { openScreen({ screenId: OVERVIEW_SCREEN, params: { focus: "paused" } }); },
+    },
+    {
+      id: "smart-session-pill",
+      title: "Smart Session: show or hide the pill",
+      icon: "ToggleLeft",
+      keywords: ["pill", "compact", "smart", "context", "ring", "enrol", "composer", "display", "show", "hide"],
+      context: "global",
+      async onSelect({ rpc }) {
+        // The same one switch as settings: the pill flag, plus the display gate when showing.
+        const { settings } = await rpc(getSettings, {});
+        const display = await rpc(displayRpc.read, {}).catch(() => null);
+        const gate = display?.status === "ready" ? displayPreferences.schema.safeParse(display.values) : null;
+        const gateOn = gate?.success ? gate.data.enable_composer_button : true;
+        const next = !(settings.showPill && gateOn);
+        if (next && gate?.success && !gateOn && display?.status === "ready") {
+          await rpc(displayRpc.write, { values: { ...gate.data, enable_composer_button: true }, revision: display.revision });
+        }
+        await rpc(setSettings, { showPill: next });
+        await refreshPills(() => rpc(enrolmentState, {}));
+      },
+    },
+  ];
+}

package/client/display.tsx

@@ -1,8 +1,6 @@
-import type { PluginClientContext, PluginSidebarItemProps, PluginSurfaceProps } from "@getpaseo/plugin/client";
-import { useSettings } from "@getpaseo/plugin/client";
-import { SettingsAction, SettingsCard, SettingsSection, SettingsSwitch, SidebarRow } from "@getpaseo/plugin/client/ui";
-import { useEffect } from "react";
-import { ActivityIndicator, ScrollView, Text, View } from "react-native";
+import type { PluginClientContext, PluginSidebarItemProps } from "@getpaseo/plugin/client";
+import { SidebarRow } from "@getpaseo/plugin/client/ui";
+import { Text } from "react-native";
 import { displayPreferences, displayRpc } from "../shared/display";
 import { Chip, useNow } from "./kit";
 import { useLive, type Live } from "./live";
@@ -14,52 +12,12 @@ 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); }; }
 
-/** 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} style={{ padding: 24 }} />;
-  if (settings.status !== "ready") return (
-    <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={{ 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>
-  );
+/** Tells the pill and the sidebar about a display document read anywhere in this bundle. */
+export function broadcastDisplay(values: Display) {
+  for (const listener of [...listeners]) listener(values);
 }
 
-/** The sidebar row, the Display settings screen, and the preference poll that drives both. */
+/** The sidebar row, and the display preference poll that drives it and the pill. */
 export function contributeDisplay(client: PluginClientContext, live: Live) {
   function SmartSessionSidebarItem({ currentScreen, openScreen, theme }: PluginSidebarItemProps) {
     useLive(live);
@@ -73,7 +31,7 @@ export function contributeDisplay(client: PluginClientContext, live: Live) {
         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)} />}
+          : <Chip theme={theme} icon={trailing.label.endsWith("paused") ? "Pause" : undefined} label={trailing.label} color={toneColor(c, trailing.tone)} />}
       />
     );
   }
@@ -83,15 +41,6 @@ export function contributeDisplay(client: PluginClientContext, live: Live) {
   // Register synchronously, then reconcile the saved preference, so that an
   // already-open sidebar route can resolve its screen during that first render.
   sidebar.set(true);
-  const removeSettings = client.addSettingsScreen({ id: "display", title: "Display", icon: "PanelLeft", Component: DisplaySettings });
-  const removeCommand = client.addCommandCenterItem({
-    id: "display-settings",
-    title: "Smart Session: display settings",
-    icon: "PanelLeft",
-    keywords: ["smart session", "sidebar", "pill", "show", "hide", "display", "settings"],
-    context: "global",
-    onSelect({ openSettings }) { openSettings("display"); },
-  });
   let disposed = false;
   let pending = false;
   let generation = 0;
@@ -105,7 +54,7 @@ export function contributeDisplay(client: PluginClientContext, live: Live) {
       const result = await client.rpc(displayRpc.read, {});
       if (!disposed && generation === currentGeneration && result.status === "ready") {
         const parsed = displayPreferences.schema.safeParse(result.values);
-        if (parsed.success) { sidebar.set(parsed.data.showSidebar); for (const listener of listeners) listener(parsed.data); }
+        if (parsed.success) { sidebar.set(parsed.data.showSidebar); broadcastDisplay(parsed.data); }
       }
     } catch {
       // Retain the last valid preference through temporary disconnects.
@@ -118,7 +67,5 @@ export function contributeDisplay(client: PluginClientContext, live: Live) {
     clearInterval(timer);
     listeners.delete(update);
     sidebar.dispose();
-    removeSettings();
-    removeCommand();
   };
 }

package/client/guard/index.tsx

@@ -1,48 +1,17 @@
 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();
-  };
+/**
+ * The pause card in the chat. The kind and version are the ones the standalone
+ * Session Guard plugin wrote, so a pause it recorded and this plugin later delivers
+ * renders the same card, and old chats keep rendering.
+ */
+export function contributeGuardTimeline(client: PluginClientContext) {
+  const openPaused = () => client.openScreen({ screenId: "overview", params: { focus: "paused" } });
+  return client.addTimelineRenderer({
+    kind: "quota-pause", version: 1, schema: TimelineDataSchema,
+    Component: (props) => <GuardTimelineItem {...props} openOverview={openPaused} />,
+  });
 }