paseo-smart-session 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Gringauz
+
+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,169 @@
+# paseo-smart-session
+
+[![Paseo](https://img.shields.io/badge/Paseo-%E2%89%A5%200.8.0-8A63D2?style=for-the-badge)](https://paseo.sh)
+[![npm downloads](https://img.shields.io/npm/dm/paseo-smart-session?style=for-the-badge&color=cb3837)](https://www.npmjs.com/package/paseo-smart-session)
+[![Release](https://img.shields.io/github/v/release/tomgrin10/paseo-smart-session?display_name=tag&sort=semver&style=for-the-badge&label=release&color=6366f1)](https://github.com/tomgrin10/paseo-smart-session/releases/latest)
+[![License](https://img.shields.io/github/license/tomgrin10/paseo-smart-session?style=for-the-badge&color=2563eb)](LICENSE)
+
+Give Paseo agents a safe way to manage long-running work.
+
+Smart Session lets an agent see how full its context is, save durable task state, and compact itself when it is ready. It also records session and plan-usage statistics, so you can understand where tokens are going and when limits 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)
+
+## What it does
+
+### Lets agents compact themselves
+
+An agent can check how much context it has used, checkpoint the work that must survive a reset, and request compaction when it reaches a safe stopping point. The agent also decides whether another turn should start afterwards and can write the exact follow-up message. A completed task can compact and stop; work in progress can resume from its saved state.
+
+The saved state captures the goal, the current step, decisions already made, and approaches that have already failed. That prevents a resumed agent from redoing work or asking a person how to continue.
+
+Smart Session never chooses to compact an agent by itself. It can let an agent know that context is filling, but the agent decides whether to checkpoint, compact, or defer.
+
+### Shows session and plan usage
+
+Smart Session keeps a local history of:
+
+- Context-window usage for each agent session
+- Claude plan usage, burn rate, and reset times
+- Token spend by model, workspace, and main agent versus subagent
+- Compaction requests and their before/after context sizes
+
+That history remains useful after an individual session ends or a provider cache changes.
+
+## Install
+
+Install from npm on Paseo 0.9.0 or newer:
+
+```sh
+paseo plugin install npm:paseo-smart-session@1.2.1
+```
+
+Paseo 0.8 can install the same plugin from Git:
+
+```sh
+paseo plugin add tomgrin10/paseo-smart-session --ref v1.2.1
+```
+
+```sh
+paseo plugin ls                    # confirm it is running
+paseo plugin update smart-session
+paseo plugin remove smart-session
+```
+
+On first load, Smart Session registers its Claude Code hooks and MCP server. It only manages entries that point at its own scripts; other Claude Code configuration is left alone.
+
+## How an agent uses it
+
+Smart Session exposes these MCP tools to Paseo agents:
+
+| Tool | What it does |
+| --- | --- |
+| `context_status` | Shows current context usage, filling rate, and relevant thresholds. |
+| `checkpoint` | Writes durable task state for the current session. |
+| `request_compaction` | Queues compaction and chooses whether and how to continue afterwards. |
+| `defer_compaction` | Defers a compaction request and records why. |
+| `budget_status` | Shows plan usage, burn rate, and reset times. |
+
+The usual flow is:
+
+```text
+context_status → checkpoint → request_compaction → stop, or re-read state and continue
+```
+
+`request_compaction` refuses when the state file is missing or stale. The agent can checkpoint and request again in the same turn.
+
+## Smart Compact
+
+Smart Compact is the session-control feature. As a session fills, hooks can provide context notices at useful thresholds. When the compact threshold is reached at the end of a turn, the agent is asked whether it wants to compact.
+
+There is no forced compaction. An agent can compact immediately, defer with a reason, or keep working. A request is delivered only when the agent is idle and its state file is current.
+
+Every request sends the `/compact` command. The agent can also set:
+
+- `continue_after_compaction: false` to finish without starting another turn.
+- `continue_after_compaction: true` to start another turn after compaction.
+- `continue_message` to choose the exact follow-up; when omitted, the default tells the agent to re-read the state file and continue from its **Current step**.
+
+Omitting the new options preserves the earlier behavior: Smart Session continues with the default state-aware prompt. The durable state wins if it disagrees with the automatic summary. A `/compact` entered by a person never receives a plugin continuation.
+
+### The composer pill
+
+The composer pill shows whether the current session is enrolled:
+
+| State | Meaning |
+| --- | --- |
+| **Smart Compact on** | The session can receive context notices and request compaction. |
+| **Smart Compact off** | The session is not enrolled. |
+
+If Smart Compact is disabled globally, the pill is not shown.
+
+## Settings
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| **Smart Compact** | On | Enables context notices and agent-requested compaction. |
+| **Large-window compact threshold** | 30% | Sets when Smart Compact asks on context windows of 400k tokens or more. |
+| **Small-window compact threshold** | 85% | Sets when Smart Compact asks on smaller context windows. |
+| **Enrol sessions automatically** | On | Enrols a session after it writes task state. |
+| **Show the pill on every agent** | On | Shows the Smart Compact control in the composer. |
+| **Register the hooks with Claude Code** | On | Keeps the context and compaction hooks installed. |
+
+The remaining settings apply only while Smart Compact is enabled. Thresholds accept whole percentages from 1% to 99%; lowering one also moves its earlier notice bands down when needed.
+
+## Usage history and state
+
+Smart Session stores its data under:
+
+```text
+$PASEO_HOME/plugin-data/smart-session/
+```
+
+| File | Contains |
+| --- | --- |
+| `usage-YYYY-MM.jsonl` | Plan-usage observations and reset times. |
+| `context-YYYY-MM.jsonl` | Context-window usage changes. |
+| `compactions.json` | Compaction requests, continuation choices, and context sizes. |
+| `spend-index.json` | Hourly token spend by model, workspace, and agent type. |
+| `state/<agentId>.md` | Durable task state for one agent. |
+| `settings.json`, `enrolment.json` | Plugin settings and per-session enrolment. |
+
+Usage and context observations are append-only. A damaged line is skipped rather than putting the rest of the history at risk. Existing compaction rows are read as “continue with the default prompt,” so upgrading requires no data migration.
+
+## Password-protected daemons
+
+When the Paseo daemon requires a password, Smart Session resolves it in this order:
+
+1. `PASEO_PASSWORD`
+2. The file named by `PASEO_PASSWORD_FILE`
+3. `~/paseo-hub/secrets/daemon-password`
+
+The secret is used only to connect to the daemon. It is never written or logged.
+
+## Develop locally
+
+```sh
+git clone https://github.com/tomgrin10/paseo-smart-session.git
+cd paseo-smart-session
+npm ci
+npm run verify
+paseo plugin install "$PWD"
+```
+
+After editing:
+
+```sh
+npm run verify
+paseo plugin reload smart-session
+```
+
+Reloading the plugin is enough. Do not restart the Paseo daemon: that interrupts every running agent.
+
+## Data and privacy
+
+Smart Session reads local Claude Code usage information and communicates with the local Paseo daemon. Its usage history, settings, and task state stay under `$PASEO_HOME`. Apart from narrowly maintaining its own Claude Code hook and MCP entries, it does not modify user configuration.
+
+## License
+
+[MIT](LICENSE) © 2026 Tom Gringauz.

package/client/charts.tsx

@@ -0,0 +1,185 @@
+import type { PluginSurfaceProps } from "@getpaseo/plugin/client";
+import React from "react";
+import { Text, View } from "react-native";
+
+import { formatTokens, rampStep } from "../shared/format";
+
+type Theme = PluginSurfaceProps["theme"];
+
+/**
+ * A sequential ramp: one hue, light to dark.
+ *
+ * Magnitude gets a single hue at stepped intensities — never a rainbow, and never
+ * the status colours, which are reserved for state. The host gives one accent hue
+ * and no scale, so the steps come from opacity over the chart surface, which is the
+ * same construction as a lightness ramp for a single hue.
+ */
+const STEPS = [0.12, 0.3, 0.5, 0.72, 1] as const;
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+/**
+ * Tokens by weekday and hour of day, in local time.
+ *
+ * The question this answers is "when am I actually working the model hardest", so
+ * the cell is the unit and the ramp carries the magnitude. Hour labels are shown
+ * every six hours: a label on all 24 would be unreadable at this width.
+ */
+export function HourHeatmap({
+  theme,
+  cells,
+  compact,
+}: {
+  theme: Theme;
+  cells: readonly { weekday: number; hour: number; tokens: number }[];
+  compact: boolean;
+}) {
+  const grid = new Map<string, number>();
+  let max = 0;
+  for (const cell of cells) {
+    grid.set(`${cell.weekday}|${cell.hour}`, cell.tokens);
+    if (cell.tokens > max) max = cell.tokens;
+  }
+
+  const size = compact ? 9 : 12;
+  const gap = 2;
+
+  return (
+    <View style={{ gap: 6 }}>
+      <View style={{ gap }}>
+        {WEEKDAYS.map((label, weekday) => (
+          <View key={label} style={{ flexDirection: "row", alignItems: "center", gap }}>
+            <Text style={{ color: theme.colors.foregroundMuted, fontSize: 10, width: 28 }}>{label}</Text>
+            {Array.from({ length: 24 }, (unused, hour) => {
+              const tokens = grid.get(`${weekday}|${hour}`) ?? 0;
+              const step = rampStep(tokens, max, STEPS.length);
+              return (
+                <View
+                  key={hour}
+                  style={{
+                    width: size,
+                    height: size,
+                    borderRadius: 2,
+                    // An empty hour is the surface, not a faint accent: absence and
+                    // "a little" must not look alike.
+                    backgroundColor: step === -1 ? theme.colors.surface2 : theme.colors.accent,
+                    opacity: step === -1 ? 0.35 : STEPS[step],
+                  }}
+                />
+              );
+            })}
+          </View>
+        ))}
+      </View>
+      <View style={{ flexDirection: "row", gap, marginLeft: 28 + gap }}>
+        {Array.from({ length: 24 }, (unused, hour) => (
+          <View key={hour} style={{ width: size, alignItems: "center" }}>
+            <Text style={{ color: theme.colors.foregroundMuted, fontSize: 9 }}>
+              {hour % 6 === 0 ? String(hour) : ""}
+            </Text>
+          </View>
+        ))}
+      </View>
+      <Text style={{ color: theme.colors.foregroundMuted, fontSize: 11 }}>
+        Local time. Darkest cell is {formatTokens(max)} tokens.
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * Tokens per day.
+ *
+ * One series, so no legend — the heading names it — and one label, on the peak,
+ * rather than a number over every bar.
+ */
+export function DailyBars({
+  theme,
+  days,
+  compact,
+}: {
+  theme: Theme;
+  days: readonly { day: string; tokens: number }[];
+  compact: boolean;
+}) {
+  if (days.length === 0) return null;
+  const max = days.reduce((peak, point) => Math.max(peak, point.tokens), 0);
+  const height = compact ? 48 : 64;
+  const peakDay = days.reduce((best, point) => (point.tokens > best.tokens ? point : best), days[0]!);
+
+  return (
+    <View style={{ gap: 6 }}>
+      <View style={{ flexDirection: "row", alignItems: "flex-end", gap: 2, height }}>
+        {days.map((point) => (
+          <View
+            key={point.day}
+            style={{
+              flex: 1,
+              height: max === 0 ? 1 : Math.max(2, (point.tokens / max) * height),
+              backgroundColor: theme.colors.accent,
+              opacity: point.day === peakDay.day ? 1 : 0.65,
+              // Rounded at the data end only; the baseline end stays square so the
+              // bar reads as anchored rather than floating.
+              borderTopLeftRadius: 3,
+              borderTopRightRadius: 3,
+            }}
+          />
+        ))}
+      </View>
+      <View style={{ flexDirection: "row", justifyContent: "space-between" }}>
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 10 }}>{days[0]!.day.slice(5)}</Text>
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 10 }}>
+          peak {peakDay.day.slice(5)} · {formatTokens(peakDay.tokens)}
+        </Text>
+        <Text style={{ color: theme.colors.foregroundMuted, fontSize: 10 }}>
+          {days[days.length - 1]!.day.slice(5)}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+/** A ranked list — a bar chart of eight rows would say the same thing with more ink. */
+export function RankedTotals({
+  theme,
+  rows,
+  total,
+}: {
+  theme: Theme;
+  rows: readonly { name: string; tokens: number }[];
+  total: number;
+}) {
+  return (
+    <View style={{ gap: 4 }}>
+      {rows.map((row) => (
+        <View key={row.name} style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          <View
+            style={{
+              flexGrow: 1,
+              height: 4,
+              borderRadius: 2,
+              backgroundColor: theme.colors.surface2,
+              overflow: "hidden",
+            }}
+          >
+            <View
+              style={{
+                width: `${total === 0 ? 0 : (row.tokens / total) * 100}%`,
+                height: 4,
+                backgroundColor: theme.colors.accent,
+              }}
+            />
+          </View>
+          <Text style={{ color: theme.colors.foreground, fontSize: 12, width: 130 }} numberOfLines={1}>
+            {row.name}
+          </Text>
+          <Text
+            style={{ color: theme.colors.foregroundMuted, fontSize: 12, fontVariant: ["tabular-nums"], width: 52, textAlign: "right" }}
+          >
+            {formatTokens(row.tokens)}
+          </Text>
+        </View>
+      ))}
+    </View>
+  );
+}