paseo-smart-session 2.1.0 → 2.2.0

package/README.md

@@ -5,9 +5,14 @@
 [![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)
 
-Let agents manage their own long-running work. Smart Session shows an agent how full its context is, lets it save durable task state, and lets it compact itself at a safe stopping point. It also keeps a history of context, plan usage and token spend.
+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.
 
-![A Smart Session compaction handoff: the requested compact preserves the task state, then the resumed session is told to re-read its state file and continue](docs/screenshots/smart-compact-handoff.png)
+<picture>
+  <source media="(prefers-color-scheme: light)" srcset="docs/media/smart-session-hero-light.png">
+  <img alt="The Smart Session screen: the headline Session runs out around 8:55 PM, 44m before the 9:39 PM reset. Below it the session window at 77% with a chart of this window's usage and the projection crossing 100% before the reset, the earlier session windows of the last 14 days, the week and the Opus week, then each session's context with its compact line" src="docs/media/smart-session-hero.png">
+</picture>
+
+Screenshots use synthetic usage history and sessions.
 
 ## Install
 
@@ -19,6 +24,19 @@ 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.
+
+- **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.
+- **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.
+
+![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)
+
 Agents get these tools:
 
 | Tool | What it does |
@@ -29,33 +47,45 @@ Agents get these tools:
 | `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 |
 
-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.
+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.
 
-The composer pill shows whether a session is enrolled in **Smart Compact**.
+![A chat after a compaction: the agent's own compaction request and the continuation as cards, a context manually compacted divider, and one-line rows for Checked plan usage and Put off compacting](docs/media/smart-session-chat.png)
 
 ## How Smart Compact works
 
-As a session fills, hooks send context notices. At the compact threshold, the agent is asked at the end of its turn whether it wants to compact. Nothing is forced: the agent can compact, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current; `request_compaction` refuses a missing or stale one.
+As a session fills, hooks send context notices. At the compact line, the agent is asked at the end of its turn whether it wants to compact. Nothing is forced: the agent can compact, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current; `request_compaction` refuses a missing or stale one.
 
 After compaction, the agent chooses to stop (`continue_after_compaction: false`), continue with the default prompt to re-read its state, or continue with its own `continue_message`. A `/compact` typed by a person never gets a plugin continuation.
 
+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:**
+
 | Setting | Default | |
 | --- | --- | --- |
 | Smart Compact | On | Context notices and agent-requested compaction |
-| Large-window compact threshold | 30% | Context windows of 400k tokens or more |
-| Small-window compact threshold | 85% | Smaller context windows |
 | Enrol sessions automatically | On | Enrol a session once it writes task state |
-| Show the pill on every agent | On | Composer pill visibility |
-| Register the hooks with Claude Code | On | Keep the context and compaction hooks installed |
+| 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 |
 
 ## Session Guard
 
 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**.
 
-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 session gets a pill to opt out or release it, and each pause gets a timeline card with **Resume now** and **Dismiss pause**. For Claude, a reset is confirmed from whichever is fresher, Paseo's cached usage or Smart Session's own recorder.
+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.
+
+![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)
 
 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.
 
+On a phone, the pill popovers open as sheets and every screen fits one column.
+
+![Smart Session at phone width: the overview, the context popover as a sheet, and Paused sessions](docs/media/smart-session-mobile.png)
+
+**Settings → Plugins → Smart Session → Display** hides the sidebar row or the composer pills; neither turns a feature off.
+
 ## Data and access
 
 Everything lives in `$PASEO_HOME/plugin-data/smart-session/`: monthly usage and context logs, compaction records, an hourly spend index by model, workspace and agent type, and one `state/<agentId>.md` per agent. Logs are append-only, and a damaged line is skipped rather than risking the rest.
@@ -79,7 +109,6 @@ paseo plugin reload smart-session   # after changes
 
 - [Defer](https://github.com/tomgrin10/paseo-defer) — Schedule messages for later delivery.
 - [Follow-up](https://github.com/tomgrin10/paseo-follow-up) — Track workspace PRs, remaining tasks and completion.
-- [Graphite](https://github.com/tomgrin10/paseo-graphite) — Graphite stacks and PR status.
 - [Send to Paseo](https://github.com/tomgrin10/send-to-paseo) — Send GitHub and Graphite PRs to Paseo from Chrome.
 - [Session Guard](https://github.com/tomgrin10/paseo-session-guard) — Pause at session limits and continue after reset.
 - [Transcript Search](https://github.com/tomgrin10/paseo-transcript-search) — Search conversations across connected hosts.

package/client/agents.ts

@@ -19,12 +19,17 @@ export interface DirectoryAgent {
   readonly workspaceId: string;
   /** Closed or archived: still listed, but no longer a session anyone is working in. */
   readonly closed: boolean;
+  /** Context occupancy as of the agent's last turn, from its snapshot; null until it has run one. */
+  readonly usedTokens: number | null;
+  readonly maxTokens: number | null;
 }
 
 export interface AgentDirectory {
   current(): ReadonlyMap<string, DirectoryAgent>;
   /** Called after every change; read `current()` for the new state. */
   subscribe(listener: () => void): () => void;
+  /** Bumped on every change, for `useSyncExternalStore`. */
+  version(): number;
   /** Releases the observation. Safe to call more than once. */
   dispose(): Promise<void>;
 }
@@ -35,6 +40,7 @@ interface ListedAgent {
   readonly workspaceId?: string | null;
   readonly status?: string;
   readonly archivedAt?: string | null;
+  readonly lastUsage?: { readonly contextWindowUsedTokens?: number; readonly contextWindowMaxTokens?: number } | null;
 }
 
 interface AgentUpdate {
@@ -56,11 +62,18 @@ interface AgentListing {
 
 function entryOf(agent: ListedAgent | undefined): [string, DirectoryAgent] | null {
   if (typeof agent?.id !== "string" || typeof agent.workspaceId !== "string" || agent.workspaceId === "") return null;
-  return [agent.id, { workspaceId: agent.workspaceId, closed: agent.status === "closed" || !!agent.archivedAt }];
+  const used = agent.lastUsage?.contextWindowUsedTokens;
+  const max = agent.lastUsage?.contextWindowMaxTokens;
+  return [agent.id, {
+    workspaceId: agent.workspaceId,
+    closed: agent.status === "closed" || !!agent.archivedAt,
+    usedTokens: typeof used === "number" && Number.isFinite(used) ? used : null,
+    maxTokens: typeof max === "number" && Number.isFinite(max) && max > 0 ? max : null,
+  }];
 }
 
 function same(a: DirectoryAgent | undefined, b: DirectoryAgent): boolean {
-  return a !== undefined && a.workspaceId === b.workspaceId && a.closed === b.closed;
+  return a !== undefined && a.workspaceId === b.workspaceId && a.closed === b.closed && a.usedTokens === b.usedTokens && a.maxTokens === b.maxTokens;
 }
 
 export function observeAgents(client: PluginClientContext): AgentDirectory {
@@ -71,13 +84,21 @@ export function observeAgents(client: PluginClientContext): AgentDirectory {
   let unsubscribeOwnedObservation: (() => void) | null = null;
   let releaseObservation: (() => Promise<void>) | null = null;
 
+  let version = 0;
   const notify = () => {
+    version += 1;
     for (const listener of [...listeners]) listener();
   };
 
   function upsert(agent: ListedAgent | undefined): boolean {
-    const entry = entryOf(agent);
-    if (entry === null || same(agents.get(entry[0]), entry[1])) return false;
+    let entry = entryOf(agent);
+    if (entry === null) return false;
+    // An update that carries no usage is not a reading of zero: keep the last one.
+    const known = agents.get(entry[0]);
+    if (entry[1].usedTokens === null && agent?.lastUsage == null && known !== undefined) {
+      entry = [entry[0], { ...entry[1], usedTokens: known.usedTokens, maxTokens: known.maxTokens }];
+    }
+    if (same(known, entry[1])) return false;
     agents.set(entry[0], entry[1]);
     return true;
   }
@@ -155,6 +176,7 @@ export function observeAgents(client: PluginClientContext): AgentDirectory {
 
   return {
     current: () => agents,
+    version: () => version,
     subscribe(listener) {
       listeners.add(listener);
       return () => {