paseo-smart-session 2.1.0 → 3.0.0

package/client/theme.ts

@@ -0,0 +1,56 @@
+import type { PluginHostProps } from "@getpaseo/plugin/client";
+import type { ViewStyle } from "react-native";
+import type { Tone } from "../shared/forecast";
+
+/**
+ * Theme-aware depth and tint, shared with the rest of the plugin family
+ * (Follow-up's client/theme.ts). Only host tokens are used: the helpers derive
+ * alphas from them rather than introducing colours of their own.
+ */
+export type Theme = PluginHostProps["theme"];
+export type Colors = Theme["colors"];
+
+function channels(color: string | undefined): number[] | null {
+  if (typeof color !== "string") return null;
+  const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim());
+  if (hex) return (hex[1].length === 3 ? [...hex[1]].map((d) => d + d) : hex[1].match(/../g)!).map((d) => parseInt(d, 16));
+  const fn = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)/i.exec(color);
+  return fn ? fn.slice(1, 4).map(Number) : null;
+}
+
+/** Light when the page ground is bright; unknown colours count as dark, Paseo's default. */
+export function isLight(colors: Colors): boolean {
+  const rgb = channels(colors.surface0);
+  if (!rgb) return false;
+  const [r, g, b] = rgb.map((v) => { const c = v / 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4; });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b > 0.4;
+}
+
+export function withAlpha(color: string, alpha: number): string {
+  const rgb = channels(color);
+  return rgb ? `rgba(${rgb.join(", ")}, ${alpha})` : color;
+}
+
+/** A tag fill in the same hue as its text: 12% on light grounds, 16% on dark ones. */
+export function tint(color: string, colors: Colors): string {
+  return withAlpha(color, isLight(colors) ? 0.12 : 0.16);
+}
+
+/** Card depth: a hairline ring plus a soft lift in light themes, a single faint ring in dark ones. */
+export function raised(colors: Colors): ViewStyle {
+  return isLight(colors)
+    ? ({ boxShadow: "0px 0px 0px 1px rgba(0, 0, 0, 0.07), 0px 1px 2px -1px rgba(0, 0, 0, 0.06), 0px 2px 6px 0px rgba(0, 0, 0, 0.04)" } as ViewStyle)
+    : ({ boxShadow: "0px 0px 0px 1px rgba(255, 255, 255, 0.08)" } as ViewStyle);
+}
+
+/** State colours: amber when a limit is near, red when it bites, green only for a resumed/finished outcome. */
+export function toneColor(colors: Colors, tone: Tone | "success" | "muted"): string {
+  switch (tone) {
+    case "success": return colors.statusSuccess;
+    case "danger": return colors.statusDanger;
+    case "warning": return colors.statusWarning;
+    default: return colors.foregroundMuted;
+  }
+}
+
+export const tabular = { fontVariant: ["tabular-nums" as const] };

package/docs/navigation-verification.md

@@ -1,11 +1,11 @@
 # Navigation verification
 
-Verified the actual plugin in an isolated Paseo 0.12.0 daemon with synthetic workspace and provider data, using the app web runtime at 1440×1000 and 390×844.
+Verified in an isolated Paseo 0.15 daemon with synthetic workspaces, usage history and sessions, using the app's web runtime at 1440×900 and 390×844, light and dark.
 
-- Sidebar main view → Display settings → Overview opens the plugin surfaces directly.
-- Compact settings have no horizontal overflow and preserve accessible native switches.
-- Existing saved sidebar preferences retain their values. Button-bearing plugins expose independent positive enable_ preferences; hiding a button does not stop its feature.
-- Graphite and Transfer header hiding/restoration were exercised through the UI; Transfer settings remained reachable from Command-K while its sidebar was hidden. Follow-up's choice survived a full page reload.
-- Button lifecycle regressions cover registrations discovered while hidden, retaining the latest descriptor, duplicate prevention, restoration and teardown.
+- The sidebar row **Smart Session** opens the overview screen; its header reads **Smart Session**, not a raw id. The row trails the session window's use, or how many sessions are paused.
+- **Paused sessions** is its own screen with its own title, opened from the overview, the Session Guard pill's menu, a pause card or Command Center.
+- Smart Compact, Session Guard and Display settings live in **Settings → Plugins → Smart Session** and open from the overview's gear, the feature cards and Command Center.
+- **Display** hides the sidebar row or the composer pills; hiding either never turns a feature off, and Command Center still opens the overview.
+- Compact settings have no horizontal overflow and keep accessible native switches.
 
 Screenshots: [desktop](screenshots/display-settings-desktop.png), [compact](screenshots/display-settings-mobile.png). Screenshots contain synthetic data. No main daemon restart or real-agent messages were used.

package/docs/session-guard.md

@@ -27,9 +27,9 @@ Every live session with a workspace gets a **Session Guard** composer pill while
 - **Session Guard settings**: configure the host policy and see paused sessions.
 - **All paused sessions**: open the host-wide overview.
 
-The **Paused sessions** sidebar view gathers every Session Guard pause on the selected host. It shows session titles and identifiers, providers, native coverage, expected reset times, and automatic/manual resume state. Uncertain stops are grouped under **Needs attention**. Open a session or manage its pause directly; search appears when the list is busy. You can also open the overview through Command Center, settings, or a timeline entry. A waiting session's composer pill begins **Paused**. Its workspace also gets an amber **Paused** label in the left sidebar. The label persists through restarts and stays until the last paused session in that workspace is released. Turn it off with **Label paused workspaces** in settings; other workspace labels stay intact.
+The **Paused sessions** screen gathers every Session Guard pause on the selected host, each led by the time its window resets and a countdown, with the session title, provider and whether native subagents are frozen or the turn was interrupted. Uncertain stops are grouped under **Needs attention**. Open a session or manage its pause directly; search appears when the list is busy. Open it from the Smart Session overview (the **2 paused** line under the headline, or the Session Guard card), the pill's menu, Command Center, settings, or a pause card. While anything is paused, the Smart Session sidebar row shows the count. A waiting session's composer pill begins **Paused**. Its workspace also gets an amber **Paused** label in the left sidebar. The label persists through restarts and stays until the last paused session in that workspace is released. Turn it off with **Label paused workspaces** in settings; other workspace labels stay intact.
 
-Confirmed pauses write a **Paused for session limit** timeline entry, including quota/reset details and whether native subagents are covered. Resume, release, and uncertain-stop entries make the recovery history clear. Existing confirmed waits are backfilled when upgrading. Timeline events use the host-owned plugin IPC identity, stay outside model messages, and never start a new turn. Delivery is journaled and retried; a lost acknowledgement is checked against timeline IDs before another append. Timeline delivery failures do not undo pauses and are shown in the overview/settings.
+Confirmed pauses write a **Paused for session limit** timeline entry: the reset time with a live countdown, the provider and how much of the window was used, and whether native subagents are covered. When the pause ends, the entry folds into one line ("Paused at 7:57 PM · resumed 9:41 PM"), so the chat keeps the history without a stale card. Resume, release, and uncertain-stop entries make the recovery history clear. Existing confirmed waits are backfilled when upgrading. Timeline events use the host-owned plugin IPC identity, stay outside model messages, and never start a new turn. Delivery is journaled and retried; a lost acknowledgement is checked against timeline IDs before another append. Timeline delivery failures do not undo pauses and are shown in the overview/settings.
 
 Choose **Dismiss pause** on an active pause or restart-recovery timeline item to release it **without sending a message**. This cancels its scheduled continuation, turns protection off for that session, clears its active pause from the overview and workspace label when applicable, and collapses the original card to a short acknowledgement. Existing suspended workers are released and may continue their current work. The dismissal is saved before release so it survives restarts; partial release retries without sending. Historical cards cannot dismiss a newer pause. **Resume now** remains available when you want Guard to continue interrupted work immediately.
 
@@ -57,7 +57,7 @@ Native coverage currently requires **Linux**, access to `/proc`, and a uniquely
 
 Suspension does not undo an API request or external action already sent. Network calls can time out while paused, and tools can retain locks. Resumption preserves local process state, but a provider's ordinary network/tool error still requires normal recovery; Session Guard automatically recovers only matching quota failures. Outstanding permission prompts remain for the person to answer.
 
-Like Smart Compact, the pill uses a state-colored icon: green when protected, muted when off, amber when paused, and red when inspection is needed. A confirmed pause timeline entry offers **Resume now** while that exact pause is still waiting. This resumes owned native workers in place, or sends one manual continuation for an interrupted turn, and opts that session out so a still-full quota cannot immediately pause it again. Restore protection from the pill when ready. Resuming does not restore provider capacity: requests can still be rejected before reset. Historical entries cannot resume a newer pause, and unconfirmed message delivery is left for inspection without a blind retry.
+The pill's icon carries its state: a shield when protected, a muted crossed-out shield when off, an amber pause while paused, and a red warning when the session needs a look. A confirmed pause timeline entry offers **Resume now** while that exact pause is still waiting. This resumes owned native workers in place, or sends one manual continuation for an interrupted turn, and opts that session out so a still-full quota cannot immediately pause it again. Restore protection from the pill when ready. Resuming does not restore provider capacity: requests can still be rejected before reset. Historical entries cannot resume a newer pause, and unconfirmed message delivery is left for inspection without a blind retry.
 
 A disposable, empty session labelled `session_guard_demo=true` can exercise the real native pause/release path through the `smart-session.guard.demo-pause` RPC (`node probe.mjs rpc smart-session.guard.demo-pause '{"agentId":"…"}'`). It must have no user messages, active turn, or pending permissions. Its timeline explicitly says **Session Guard demo paused**, makes no quota claim, and waits for your action even when capacity resets. The demo never sends a task or changes provider quota reports.
 

package/index.client.tsx

@@ -1,53 +1,65 @@
 import { withButtonVisibility } from "./client/button-visibility";
 import { contributeDisplay } from "./client/display";
-import { withNavigation } from "./client/navigation";
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 
 import { observeAgents } from "./client/agents";
+import { contributeChat } from "./client/chat";
 import { contributeGuardClient } from "./client/guard/index";
+import { createLive } from "./client/live";
+import { OVERVIEW_SCREEN, SMART_COMPACT_SETTINGS, makeOverview } from "./client/overview";
 import { contributeClient, refreshPills } from "./client/pill";
-import { SmartSessionSurface } from "./client/surface";
+import { SmartCompactSettings } from "./client/settings";
 import { enrolmentState } from "./shared/governor";
-import { getSettings, setSettings } from "./shared/smart-session";
+import { budgetStatus, getSettings, setSettings } from "./shared/smart-session";
 
 export default function contribute(host: PluginClientContext) {
   const visibility = withButtonVisibility(host);
   const client = visibility.client;
-  client.addSurface("overview", withNavigation((props) => <SmartSessionSurface {...props} openSurface={client.openSurface} />, client, "overview"));
-  const removeDisplay = contributeDisplay(client, {
-    id: "smart-session",
-    title: "Smart Session",
-    icon: "Gauge",
-    surface: "overview",
-  });
+  const live = createLive();
+  const removers = [
+    client.addScreen({ id: OVERVIEW_SCREEN, title: "Smart Session", Component: makeOverview(client, live) }),
+    client.addSettingsScreen({ id: SMART_COMPACT_SETTINGS, title: "Smart Compact", icon: "FoldVertical", Component: SmartCompactSettings }),
+    contributeDisplay(client, live),
+    client.addCommandCenterItem({
+      id: "smart-session-open",
+      title: "Smart Session: plan usage and context",
+      icon: "Gauge",
+      keywords: ["usage", "budget", "limit", "forecast", "context", "tokens", "compact", "smart session"],
+      context: "global",
+      onSelect({ openScreen }) {
+        openScreen({ screenId: OVERVIEW_SCREEN });
+      },
+    }),
+    client.addCommandCenterItem({
+      id: "smart-session-pill",
+      title: "Show or hide the context pill",
+      icon: "ToggleLeft",
+      keywords: ["pill", "compact", "smart", "context", "ring", "enrol"],
+      context: "global",
+      async onSelect({ rpc }) {
+        const { settings } = await rpc(getSettings, {});
+        await rpc(setSettings, { showPill: !settings.showPill });
+        await refreshPills(() => rpc(enrolmentState, {}));
+      },
+    }),
+    contributeChat(client),
+  ];
 
-  client.addCommandCenterItem({
-    id: "smart-session-open",
-    title: "Show plan usage and agent context",
-    icon: "Gauge",
-    keywords: ["usage", "budget", "limit", "context", "tokens", "compact"],
-    context: "global",
-    onSelect({ openSurface }) {
-      openSurface("overview");
-    },
-  });
-
-  client.addCommandCenterItem({
-    id: "smart-session-pill",
-    title: "Show or hide the smart-compact pill",
-    icon: "ToggleLeft",
-    keywords: ["pill", "compact", "smart", "governor", "enrol"],
-    context: "global",
-    async onSelect({ rpc }) {
-      const { settings } = await rpc(getSettings, {});
-      await rpc(setSettings, { showPill: !settings.showPill });
-      await refreshPills(() => rpc(enrolmentState, {}));
-    },
-  });
+  // The sidebar row shows the session window between overview visits.
+  const readBudget = () => client.rpc(budgetStatus, {}).then((budget) => live.setBudget(budget)).catch(() => undefined);
+  void readBudget();
+  const budgetTimer = setInterval(() => void readBudget(), 2 * 60_000);
 
   // One agent observation for every pill in this bundle.
   const agents = observeAgents(client);
   const removeClient = contributeClient(client, agents);
-  const removeGuard = contributeGuardClient(client, agents, "overview");
-  return () => { removeGuard(); removeClient(); visibility.dispose(); removeDisplay(); return agents.dispose(); };
+  const removeGuard = contributeGuardClient(client, agents, live);
+  return () => {
+    clearInterval(budgetTimer);
+    removeGuard();
+    removeClient();
+    for (const remove of removers.splice(0)) void remove();
+    visibility.dispose();
+    return agents.dispose();
+  };
 }

package/index.server.ts

@@ -7,7 +7,7 @@ import { readAgents, withDaemon } from "./server/daemon.ts";
 import { contextGrowth, projectFull } from "./server/growth.ts";
 import { install } from "./server/install.ts";
 import { summarizeSpend } from "./server/spend.ts";
-import { countEnrolled, listEnrolment, readSettings, setEnrolled, writeSettings } from "./server/settings.ts";
+import { countEnrolled, listEnrolment, readSettings, setEnrolled, stateWrittenAt, writeSettings } from "./server/settings.ts";
 import { dataDir, newestUsage, readUsage } from "./server/store.ts";
 import {
   budgetStatus,
@@ -25,7 +25,7 @@ import {
   requestCompaction,
   setEnrolment,
 } from "./shared/governor.ts";
-import { burnRatePctPerHour, projectedExhaustion, segmentBlocks } from "./shared/blocks.ts";
+import { burnRatePctPerHour, projectedExhaustion, segmentBlocks, thinPoints } from "./shared/blocks.ts";
 import { lifecycle, runTeardowns } from "./shared/lifecycle.ts";
 import { profileFor } from "./shared/thresholds.ts";
 import { effectiveAt } from "./shared/usage.ts";
@@ -52,8 +52,9 @@ export default function contribute(server: PluginServerContext) {
       const newest = await newestUsage();
 
       // One row per window, taken from its currently open block.
-      const open = new Map<string, ReturnType<typeof segmentBlocks>[number]>();
-      for (const block of segmentBlocks(samples)) open.set(block.windowId, block);
+      const blocks = segmentBlocks(samples);
+      const open = new Map<string, (typeof blocks)[number]>();
+      for (const block of blocks) open.set(block.windowId, block);
 
       const windows = [...open.values()]
         .map((block) => ({
@@ -62,12 +63,19 @@ export default function contribute(server: PluginServerContext) {
           resetsAt: block.resetsAt,
           burnPctPerHour: burnRatePctPerHour(block),
           projectedFullAt: projectedExhaustion(block),
+          startAt: block.startAt,
+          history: thinPoints(block.points, 96),
         }))
         .sort((a, b) => b.pct - a.pct);
+      const current = open.get("five_hour");
+      const past = blocks
+        .filter((block) => block.windowId === "five_hour" && block !== current)
+        .map((block) => ({ startAt: block.startAt, resetsAt: block.resetsAt, firstSeenAt: block.firstSeenAt, peakPct: block.peakPct }));
 
       const newestInstant = newest === null ? null : effectiveAt(newest);
       return {
         windows,
+        past,
         recorder: {
           newestAt: newestInstant,
           ageSeconds:
@@ -116,6 +124,7 @@ export default function contribute(server: PluginServerContext) {
           growthTokensPerHour: growth.get(row.id) ?? null,
           projectedFullAt: projectFull(row.usedTokens!, row.maxTokens!, growth.get(row.id) ?? null, thresholds),
           compactAtPct: profileFor(row.maxTokens!, thresholds).compact,
+          stateWrittenAt: stateWrittenAt(row.id),
         }))
         .sort((a, b) => b.usedPct - a.usedPct);
       return { agents, error: null };
@@ -186,7 +195,7 @@ export default function contribute(server: PluginServerContext) {
 
   server.handle(enrolmentState, async () => {
     const settings = await readSettings();
-    return { showPill: settings.showPill, enabled: settings.enabled, agents: await listEnrolment() };
+    return { showPill: settings.showPill, enabled: settings.enabled, agents: await listEnrolment(), thresholds: settings.thresholds };
   });
 
   server.handle(setEnrolment, async ({ agentId, enrolled }) => ({

package/mcp.mjs

@@ -454,7 +454,7 @@ const TOOLS = {
       const agentId = requireAgent();
       const settings = readSettings();
       if (!settings.enabled) {
-        return "Smart Compact is switched off for this Paseo install, so nothing would deliver this request. Compact by hand if you need to, or ask the user to turn Smart Compact on in the Smart Session surface.";
+        return "Smart Compact is switched off for this Paseo install, so nothing would deliver this request. Compact by hand if you need to, or ask the user to turn Smart Compact on in the Smart Session screen or Settings → Plugins → Smart Session.";
       }
 
       // Default to this session's own state file: the whole point is that the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "paseo-smart-session",
   "type": "module",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "license": "MIT",
   "description": "Records Claude plan-usage history and lets a Paseo agent manage its own context.",
   "repository": {

package/paseo-plugin.json

@@ -1,6 +1,16 @@
 {
   "id": "smart-session",
+  "name": "Smart Session",
   "icon": "assets/icon.png",
+  "description": "See when your plan runs out at this pace, how full each session's context is, and let agents checkpoint and compact themselves. Session Guard pauses work at the session limit and continues it after the reset.",
+  "media": [
+    "docs/media/smart-session-hero.png",
+    "docs/media/smart-session-flow.gif",
+    "docs/media/smart-session-pill.png",
+    "docs/media/smart-session-chat.png",
+    "docs/media/smart-session-guard.png",
+    "docs/media/smart-session-mobile.png"
+  ],
   "requirements": {
     "paseo": ">=0.14.0"
   }

package/server/settings.ts

@@ -7,6 +7,7 @@
 
 import { randomUUID } from "node:crypto";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { statSync } from "node:fs";
 import { join } from "node:path";
 
 import { dataDir } from "./store.ts";
@@ -130,6 +131,15 @@ export function statePathFor(agentId: string): string {
   return join(dataDir(), "state", `${agentId}.md`);
 }
 
+/** When an agent last wrote its task state, or null when it never has. */
+export function stateWrittenAt(agentId: string): string | null {
+  try {
+    return new Date(statSync(statePathFor(agentId)).mtimeMs).toISOString();
+  } catch {
+    return null;
+  }
+}
+
 
 /**
  * Whether the governor may speak to one agent, and who decided.

package/shared/blocks.ts

@@ -206,3 +206,18 @@ export function projectedExhaustion(block: Block, now = new Date()): string | nu
   if (block.resetsAt !== null && at > Date.parse(block.resetsAt)) return null;
   return new Date(at).toISOString();
 }
+
+/**
+ * At most `max` points from a block, for a chart.
+ *
+ * Keeps the first and last points and every turn of the curve a chart can show; drops
+ * the rest evenly. The percentage only climbs within one window, so an even stride
+ * loses nothing a 96-column chart could draw.
+ */
+export function thinPoints(points: readonly BlockPoint[], max: number): BlockPoint[] {
+  if (points.length <= max || max < 2) return [...points];
+  const stride = (points.length - 1) / (max - 1);
+  const out: BlockPoint[] = [];
+  for (let i = 0; i < max; i++) out.push(points[Math.round(i * stride)]!);
+  return out;
+}

package/shared/chat.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+
+/**
+ * Smart Session's agent tools and plugin-sent messages as they appear in a chat,
+ * reduced to what a one-line row or a small card needs. Pure, so the transformer and
+ * the tests read the same rules.
+ */
+export const TOOL_ROW_KIND = "smart-session-tool";
+export const PROMPT_CARD_KIND = "smart-session-prompt";
+
+export const SMART_SESSION_TOOLS = ["context_status", "checkpoint", "request_compaction", "defer_compaction", "budget_status"] as const;
+export type SmartSessionTool = (typeof SMART_SESSION_TOOLS)[number];
+
+export const ToolRowSchema = z.object({
+  tool: z.enum(SMART_SESSION_TOOLS),
+  state: z.enum(["running", "done", "refused", "failed"]),
+  /** The one line, e.g. "Checked its context · 32% of 1M · compacts at 30%". */
+  line: z.string(),
+  /** What opens under it: the call's own words, trimmed. Empty when there is nothing more. */
+  detail: z.string(),
+});
+export type ToolRow = z.infer<typeof ToolRowSchema>;
+
+export const PromptCardSchema = z.object({
+  kind: z.enum(["compact", "continue", "guard-continue", "guard-resume"]),
+  /** compact: the reason the agent gave. */
+  reason: z.string(),
+  /** compact / continue: the state file it re-reads, when named. */
+  statePath: z.string(),
+  text: z.string(),
+});
+export type PromptCard = z.infer<typeof PromptCardSchema>;
+
+/** Claude records mcp__smart-session__context_status; Codex records smart-session.context_status. */
+export function smartSessionTool(name: string): SmartSessionTool | null {
+  const match = /^(?:mcp__)?smart-session(?:__|\.|\/|:)([a-z_]+)$/.exec(name);
+  return match && (SMART_SESSION_TOOLS as readonly string[]).includes(match[1]!) ? (match[1] as SmartSessionTool) : null;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The text a tool result carries, however the provider wrapped it. */
+export function readText(value: unknown): string | undefined {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const parts = value.map((part) => (typeof part === "string" ? part : record(part) && typeof part.text === "string" ? part.text : undefined));
+    return parts.every((part) => part !== undefined) ? parts.join("\n") : undefined;
+  }
+  if (!record(value)) return undefined;
+  const key = ["content", "output", "text", "message", "result"].find((name) => name in value);
+  return key ? readText(value[key]) : undefined;
+}
+
+const str = (value: unknown) => (typeof value === "string" ? value.trim() : "");
+const clip = (value: string, max: number) => (value.length > max ? `${value.slice(0, max - 1).trimEnd()}…` : value);
+const oneLine = (value: string) => value.replace(/\s+/g, " ").trim();
+
+/** "1,000,000" → "1M", "200,000" → "200k". */
+function size(raw: string): string {
+  const n = Number(raw.replace(/,/g, ""));
+  if (!Number.isFinite(n)) return raw;
+  return n >= 1_000_000 ? `${Number((n / 1_000_000).toFixed(1))}M` : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+
+function contextLine(output: string): string {
+  if (/^No context reading/i.test(output)) return "Checked its context · no reading yet";
+  const m = /\(([\d.]+)% of a ([\d,]+)-token window\)\. Worth compacting from (\d+)%/.exec(output);
+  if (!m) return "Checked its context";
+  const past = /already past that point/i.test(output);
+  return `Checked its context · ${Math.round(Number(m[1]))}% of ${size(m[2]!)} · ${past ? `past its ${m[3]}% line` : `compacts at ${m[3]}%`}`;
+}
+
+function budgetLine(output: string): string {
+  if (/^Could not read plan usage/i.test(output)) return "Couldn't read plan usage";
+  const parts: string[] = [];
+  for (const m of output.matchAll(/^- (Session \(5h\)|Week|[^:]+): (\d+)% used/gm)) {
+    const name = m[1] === "Session (5h)" ? "session" : m[1] === "Week" ? "week" : m[1]!;
+    parts.push(`${name} ${m[2]}%`);
+  }
+  return parts.length === 0 ? "Checked plan usage" : `Checked plan usage · ${parts.slice(0, 2).join(" · ")}`;
+}
+
+function checkpointDetail(input: Record<string, unknown>): string {
+  const lines: string[] = [];
+  const add = (label: string, value: unknown) => {
+    if (typeof value === "string" && value.trim()) lines.push(`${label}: ${value.trim()}`);
+    else if (Array.isArray(value)) for (const item of value) if (typeof item === "string" && item.trim()) lines.push(`${label}: ${item.trim()}`);
+  };
+  add("Goal", input.goal); add("Plan", input.plan); add("Current step", input.current_step);
+  add("Decision", input.decisions); add("Dead end", input.dead_ends); add("Key fact", input.key_facts);
+  return clip(lines.join("\n"), 4000);
+}
+
+/** Builds a row from a tool call, or null when the call is not one of Smart Session's. */
+export function toolRow(name: string, status: string, detail: unknown, error: unknown): ToolRow | null {
+  const tool = smartSessionTool(name);
+  if (tool === null) return null;
+  const input = record(detail) && record(detail.input) ? detail.input : {};
+  const output = record(detail) && "output" in detail ? (readText(detail.output) ?? "") : "";
+  const failedOutput = record(detail) && record(detail.output) && detail.output.isError === true;
+  const failed = status === "failed" || failedOutput || /^Failed: /.test(output);
+  const running = !failed && status !== "completed";
+  if (failed) {
+    const why = clip(oneLine(readText(error) || output.replace(/^Failed: /, "") || ""), 500);
+    return { tool, state: "failed", line: `Smart Session couldn't ${tool === "checkpoint" ? "save task state" : tool === "request_compaction" ? "queue the compaction" : tool === "defer_compaction" ? "put off compacting" : tool === "budget_status" ? "read plan usage" : "read the context"}`, detail: why };
+  }
+  switch (tool) {
+    case "context_status":
+      return { tool, state: running ? "running" : "done", line: running ? "Checking its context…" : contextLine(output), detail: clip(output, 2000) };
+    case "budget_status":
+      return { tool, state: running ? "running" : "done", line: running ? "Checking plan usage…" : budgetLine(output), detail: clip(output, 2000) };
+    case "checkpoint": {
+      const step = str(input.current_step);
+      const added = /\((\d+) new entr/.exec(output)?.[1];
+      const line = running ? "Saving task state…" : `Saved task state${step ? ` · ${clip(oneLine(step), 90)}` : added ? ` · ${added} new ${added === "1" ? "entry" : "entries"}` : ""}`;
+      return { tool, state: running ? "running" : "done", line, detail: checkpointDetail(input) };
+    }
+    case "request_compaction": {
+      const reason = clip(oneLine(str(input.reason)), 110);
+      const continues = input.continue_after_compaction !== false;
+      const message = str(input.continue_message);
+      const detailText = [
+        reason ? `Reason: ${str(input.reason)}` : "",
+        continues ? (message ? `Then: ${message}` : "Then: re-read the task state and carry on") : "Then: stop, the task is done",
+      ].filter(Boolean).join("\n");
+      if (running) return { tool, state: "running", line: "Asking to compact…", detail: detailText };
+      if (/^Not queued|switched off/i.test(output)) {
+        const why = /switched off/i.test(output) ? "Smart Compact is off" : /no task state/i.test(output) ? "no task state saved yet" : /last written/i.test(output) ? "task state is out of date" : "refused";
+        return { tool, state: "refused", line: `Compaction not queued · ${why}`, detail: clip(output, 1500) };
+      }
+      return { tool, state: "done", line: `Asked to compact${continues ? "" : " and stop"}${reason ? ` · ${reason}` : ""}`, detail: detailText };
+    }
+    case "defer_compaction": {
+      const reason = clip(oneLine(str(input.reason)), 110);
+      const minutes = /Deferred for (\d+) minutes/.exec(output)?.[1] ?? (typeof input.minutes === "number" ? String(input.minutes) : null);
+      return { tool, state: running ? "running" : "done", line: running ? "Putting off compacting…" : `Put off compacting${minutes ? ` for ${minutes}m` : ""}${reason ? ` · ${reason}` : ""}`, detail: clip(output, 1500) };
+    }
+  }
+}
+
+const COMPACT_PREFIX = "/compact Preserve: the current goal";
+const CONTINUE_PREFIX = "That compaction was the one you asked for.";
+const GUARD_DEFAULT_PREFIX = "Your previous turn was paused because the provider's session usage limit was reached.";
+const GUARD_RESUME_PREFIX = "You explicitly chose Resume now while Session Guard was waiting";
+
+/**
+ * Recognises the messages Smart Session itself sends into a chat: the /compact an
+ * agent asked for, the continuation after it, and Session Guard's continuation and
+ * Resume now. Anything else, including a person's own /compact, is left alone.
+ */
+export function promptCard(text: string): PromptCard | null {
+  const body = text.trim();
+  if (body.startsWith(COMPACT_PREFIX)) {
+    const reason = /Reason for compacting now: ([\s\S]*?)(?: Authoritative state lives at |$)/.exec(body)?.[1]?.trim() ?? "";
+    const statePath = /Authoritative state lives at (.+?)\. Re-read that file/.exec(body)?.[1]?.trim() ?? "";
+    return { kind: "compact", reason, statePath, text: body };
+  }
+  if (body.startsWith(CONTINUE_PREFIX)) {
+    const statePath = /^That compaction was the one you asked for\. Re-read (.+?) and continue from/.exec(body)?.[1]?.trim() ?? "";
+    return { kind: "continue", reason: "", statePath, text: body };
+  }
+  if (body.startsWith(GUARD_DEFAULT_PREFIX)) return { kind: "guard-continue", reason: "", statePath: "", text: body };
+  if (body.startsWith(GUARD_RESUME_PREFIX)) return { kind: "guard-resume", reason: "", statePath: "", text: body };
+  return null;
+}
+
+/** The last path segment, for a state file named in a card. */
+export function fileName(path: string): string {
+  const parts = path.split(/[\\/]/).filter(Boolean);
+  return parts[parts.length - 1] ?? path;
+}