paseo-smart-session 1.2.1

package/shared/blocks.ts

@@ -0,0 +1,208 @@
+/**
+ * Turning a stream of samples into the thing you actually want to look at:
+ * one record per limit window occurrence — a "block".
+ */
+
+import { effectiveAt, type UsageSample, type WindowSample } from "./usage.ts";
+
+/**
+ * How far two reported resets may differ and still be the same window.
+ *
+ * The provider re-derives the reset instant on every read, so the same window
+ * comes back as "…:59.873850" then "…:00.309167". Compared exactly, every refresh
+ * looks like a rollover. (Learned the hard way in paseo-defer; see its
+ * `paseo-defer/server/engine.ts`.)
+ */
+const SAME_WINDOW_TOLERANCE_MS = 120_000;
+
+/** Nominal lengths, used only to place a block's start on a timeline. */
+const WINDOW_DURATION_MS: Readonly<Record<string, number>> = {
+  five_hour: 5 * 60 * 60 * 1000,
+  seven_day: 7 * 24 * 60 * 60 * 1000,
+};
+
+/** A stretch with no samples, long enough that a chart must not draw across it. */
+export interface Gap {
+  readonly from: string;
+  readonly to: string;
+}
+
+export interface BlockPoint {
+  readonly t: string;
+  readonly pct: number;
+}
+
+export interface Block {
+  readonly windowId: string;
+  /** The window's rollover instant, as last reported. */
+  readonly resetsAt: string | null;
+  /** resetsAt minus the window's nominal length; null when the length is unknown. */
+  readonly startAt: string | null;
+  readonly firstSeenAt: string;
+  readonly lastSeenAt: string;
+  readonly peakPct: number;
+  readonly finalPct: number;
+  readonly points: readonly BlockPoint[];
+  readonly gaps: readonly Gap[];
+  readonly scope?: string;
+}
+
+/** One instant format, whatever spelling the source used. */
+function normalize(value: string | null): string | null {
+  if (value === null) return null;
+  const ms = Date.parse(value);
+  return Number.isNaN(ms) ? null : new Date(ms).toISOString();
+}
+
+function sameWindow(a: string | null, b: string | null): boolean {
+  if (a === null || b === null) return a === b;
+  return Math.abs(Date.parse(a) - Date.parse(b)) <= SAME_WINDOW_TOLERANCE_MS;
+}
+
+/**
+ * Whether `next` is a genuinely later window than `current`.
+ *
+ * A new window always ends later than the one it replaced. An *earlier* reported
+ * reset is the provider revising the window we are already in, never a rollover —
+ * treating it as one attributes the rest of the block to the wrong occurrence.
+ */
+function isRollover(current: string | null, next: string | null): boolean {
+  if (next === null) return false;
+  if (current === null) return true;
+  return Date.parse(next) - Date.parse(current) > SAME_WINDOW_TOLERANCE_MS;
+}
+
+interface OpenBlock {
+  windowId: string;
+  resetsAt: string | null;
+  scope?: string;
+  points: BlockPoint[];
+  gaps: Gap[];
+}
+
+function seal(open: OpenBlock): Block {
+  const points = open.points;
+  const first = points[0]!;
+  const last = points[points.length - 1]!;
+  const duration = WINDOW_DURATION_MS[open.windowId.split(":")[0]!];
+  return {
+    windowId: open.windowId,
+    resetsAt: open.resetsAt,
+    startAt:
+      open.resetsAt !== null && duration !== undefined
+        ? new Date(Date.parse(open.resetsAt) - duration).toISOString()
+        : null,
+    firstSeenAt: first.t,
+    lastSeenAt: last.t,
+    peakPct: points.reduce((peak, point) => Math.max(peak, point.pct), 0),
+    finalPct: last.pct,
+    points,
+    gaps: open.gaps,
+    ...(open.scope !== undefined ? { scope: open.scope } : {}),
+  };
+}
+
+/**
+ * Segment samples into blocks, newest last.
+ *
+ * `gapMs` should exceed the recorder's heartbeat: anything longer than that means
+ * nobody was watching, which is a fact about the recorder and must stay visible in
+ * the output rather than being smoothed over.
+ */
+export function segmentBlocks(
+  samples: readonly UsageSample[],
+  options: { readonly gapMs?: number } = {},
+): Block[] {
+  const gapMs = options.gapMs ?? 15 * 60 * 1000;
+  const ordered = [...samples].sort((a, b) => Date.parse(effectiveAt(a)) - Date.parse(effectiveAt(b)));
+
+  const open = new Map<string, OpenBlock>();
+  const sealed: Block[] = [];
+
+  for (const sample of ordered) {
+    // One instant format in, whatever the source spelled it as.
+    const t = new Date(Date.parse(effectiveAt(sample))).toISOString();
+    for (const [windowId, window] of Object.entries(sample.windows)) {
+      const current = open.get(windowId);
+      if (current === undefined) {
+        open.set(windowId, startBlock(windowId, window, t));
+        continue;
+      }
+
+      if (isRollover(current.resetsAt, window.resetsAt)) {
+        sealed.push(seal(current));
+        open.set(windowId, startBlock(windowId, window, t));
+        continue;
+      }
+
+      // Not a rollover: adopt a reset instant we did not have, keep the one we did.
+      if (current.resetsAt === null && window.resetsAt !== null) current.resetsAt = normalize(window.resetsAt);
+      else if (!sameWindow(current.resetsAt, window.resetsAt) && window.resetsAt !== null) {
+        // Reported earlier than what we hold — a revision. Keep the block, take the value.
+        current.resetsAt = normalize(window.resetsAt);
+      }
+
+      const previous = current.points[current.points.length - 1]!;
+      if (Date.parse(t) - Date.parse(previous.t) > gapMs) {
+        current.gaps.push({ from: previous.t, to: t });
+      }
+      current.points.push({ t, pct: window.pct });
+    }
+  }
+
+  for (const current of open.values()) sealed.push(seal(current));
+  return sealed.sort((a, b) => Date.parse(a.firstSeenAt) - Date.parse(b.firstSeenAt));
+}
+
+function startBlock(windowId: string, window: WindowSample, t: string): OpenBlock {
+  return {
+    windowId,
+    resetsAt: normalize(window.resetsAt),
+    ...(window.scope !== undefined ? { scope: window.scope } : {}),
+    points: [{ t, pct: window.pct }],
+    gaps: [],
+  };
+}
+
+/**
+ * Burn rate in percentage points per hour over *at least* the block's most recent
+ * `spanMs`.
+ *
+ * The anchor is the last point at or before the cutoff, not the first one after
+ * it. Samples are only written when something changes, so a quiet stretch may hold
+ * a single point inside any given span — anchoring inside the window would make
+ * the span zero and the rate unreportable exactly when the answer is "flat".
+ */
+export function burnRatePctPerHour(block: Block, spanMs = 30 * 60 * 1000): number | null {
+  const points = block.points;
+  if (points.length < 2) return null;
+  const last = points[points.length - 1]!;
+  const cutoff = Date.parse(last.t) - spanMs;
+
+  let index = points.findIndex((point) => Date.parse(point.t) >= cutoff);
+  if (index === -1) index = points.length - 1;
+  if (index > 0) index -= 1;
+
+  const first = points[index]!;
+  const hours = (Date.parse(last.t) - Date.parse(first.t)) / 3_600_000;
+  if (hours <= 0) return null;
+  return (last.pct - first.pct) / hours;
+}
+
+/**
+ * When this block reaches 100% at the current burn rate.
+ *
+ * Null when it is not burning, or when it would exhaust after the window rolls
+ * over anyway — in which case there is nothing to warn about.
+ */
+export function projectedExhaustion(block: Block, now = new Date()): string | null {
+  const rate = burnRatePctPerHour(block);
+  if (rate === null || rate <= 0) return null;
+  const last = block.points[block.points.length - 1]!;
+  const hoursLeft = (100 - last.pct) / rate;
+  if (!Number.isFinite(hoursLeft) || hoursLeft < 0) return null;
+  const at = Date.parse(last.t) + hoursLeft * 3_600_000;
+  if (at < now.getTime()) return null;
+  if (block.resetsAt !== null && at > Date.parse(block.resetsAt)) return null;
+  return new Date(at).toISOString();
+}

package/shared/format.ts

@@ -0,0 +1,82 @@
+/** Small formatters shared by the surface and any future CLI. */
+
+/** "2h 14m", "4m", "now" — a duration a person reads without decoding. */
+export function formatDuration(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "now";
+  const minutes = Math.round(ms / 60_000);
+  if (minutes < 1) return "under a minute";
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  if (hours < 24) return rest === 0 ? `${hours}h` : `${hours}h ${rest}m`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ${hours % 24}h`;
+}
+
+/** "in 2h 14m" / "14m ago", relative to now. */
+export function formatRelative(iso: string | null, now = Date.now()): string {
+  if (iso === null) return "—";
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) return "—";
+  return ms >= now ? `in ${formatDuration(ms - now)}` : `${formatDuration(now - ms)} ago`;
+}
+
+/** "261.7k" — token counts, which are always large and never need units. */
+export function formatTokens(count: number): string {
+  if (count < 1000) return String(count);
+  if (count < 1_000_000) return `${(count / 1000).toFixed(count < 10_000 ? 1 : 0)}k`;
+  return `${(count / 1_000_000).toFixed(2)}M`;
+}
+
+/** A window id turned into something worth putting on a row. */
+export function windowLabel(id: string): string {
+  if (id === "five_hour") return "Session (5h)";
+  if (id === "seven_day") return "Week";
+  const scoped = /^weekly_(model|surface):(.+)$/.exec(id);
+  if (scoped !== null) {
+    const name = scoped[2]!;
+    return `Week · ${name.charAt(0).toUpperCase()}${name.slice(1)}`;
+  }
+  return id;
+}
+
+/**
+ * Which windows are worth a row.
+ *
+ * The provider reports a long tail of caps that are inactive, unnamed, or at zero
+ * for this account — internal codenames included. Showing them all buries the two
+ * that matter.
+ */
+export function isInteresting(window: { id: string; pct: number; resetsAt: string | null }): boolean {
+  if (window.id === "five_hour" || window.id === "seven_day") return true;
+  return window.pct > 0 || window.resetsAt !== null;
+}
+
+
+/**
+ * Which step of a sequential ramp a value falls on.
+ *
+ * Magnitude is encoded with one hue at stepped intensities, so this returns an
+ * index into that ramp — or -1 for "no data", which must render as the surface
+ * rather than as the faintest step: absence and "a little" must not look alike.
+ */
+export function rampStep(value: number, max: number, steps: number): number {
+  if (steps <= 0 || max <= 0 || value <= 0) return -1;
+  const index = Math.ceil((value / max) * steps) - 1;
+  return Math.min(steps - 1, Math.max(0, index));
+}
+
+/**
+ * What the composer pill says about one agent.
+ *
+ * "Smart Compact" rather than "auto-compact": Claude Code already ships a feature
+ * by the latter name that fires on its own thresholds, and a pill that borrowed the
+ * name would read as a switch for that.
+ *
+ * Two states, because there are only two. Whether this session is governed is the
+ * only question a pill can answer; whether the feature exists at all is answered by
+ * the pill being drawn, since it is hidden entirely when Smart Compact is off.
+ */
+export function smartCompactLabel(input: { enrolled: boolean }): string {
+  return input.enrolled ? "Smart Compact on" : "Smart Compact off";
+}

package/shared/governor.ts

@@ -0,0 +1,178 @@
+/**
+ * The Governor: letting an agent compact itself.
+ *
+ * An agent cannot run `/compact` — it is a client command, not something the model
+ * can invoke. But Paseo parses slash commands out of any message sent to an agent
+ * and honours the root-only set, `compact` included, so a request routed through
+ * the daemon becomes a real compaction with real custom instructions. Verified end
+ * to end: 39,325 -> 6,160 tokens with instructions honoured (RESEARCH.md §7.1).
+ */
+
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const CompactionStateSchema = z.enum(["pending", "sending", "sent", "failed", "cancelled"]);
+
+export const CompactionRequestSchema = z.object({
+  id: z.string(),
+  agentId: z.string(),
+  /** Why the agent asked, in its own words. Goes into the compaction instructions. */
+  reason: z.string(),
+  /** A file the agent considers authoritative, re-read after compaction. */
+  statePath: z.string().nullable(),
+  /** Whether to start another model turn after the compaction lands. */
+  continueAfterCompaction: z.boolean(),
+  /** Exact follow-up chosen by the agent, or null for the state-aware default. */
+  continuationMessage: z.string().nullable(),
+  createdAt: z.string(),
+  state: CompactionStateSchema,
+  settledAt: z.string().nullable(),
+  error: z.string().nullable(),
+  /** Context occupancy either side of the compaction, for grading the policy. */
+  preTokens: z.number().nullable(),
+  postTokens: z.number().nullable(),
+  /**
+   * When the requested continuation message was sent.
+   *
+   * Nothing in Claude Code restarts a task after a manual `/compact` — verified
+   * across 190 real compactions, 163 of which stopped dead waiting for a person
+   * (`RESEARCH.md` §3.4). When the agent wants to keep working, the governor says
+   * the default or agent-supplied follow-up once and records that it did.
+   */
+  resumedAt: z.string().nullable(),
+});
+export type CompactionRequest = z.infer<typeof CompactionRequestSchema>;
+
+/**
+ * Queues a compaction for an agent, delivered once that agent is idle.
+ *
+ * Never delivered mid-turn: a message arriving during a turn steers it instead of
+ * arriving as its own instruction, and a compaction that interrupts a half-finished
+ * tool sequence loses exactly the state the agent had not written down yet.
+ */
+export const requestCompaction = defineRpc({
+  name: "smart-session.compact.request",
+  input: z.object({
+    agentId: z.string(),
+    reason: z.string(),
+    statePath: z.string().nullable().optional(),
+    continueAfterCompaction: z.boolean().optional(),
+    continuationMessage: z.string().min(1).nullable().optional(),
+  }),
+  output: z.object({ request: CompactionRequestSchema }),
+});
+
+export const listCompactions = defineRpc({
+  name: "smart-session.compact.list",
+  input: z.object({ agentId: z.string().optional() }),
+  output: z.object({ items: z.array(CompactionRequestSchema) }),
+});
+
+export const cancelCompaction = defineRpc({
+  name: "smart-session.compact.cancel",
+  input: z.object({ id: z.string() }),
+  output: z.object({ ok: z.boolean() }),
+});
+
+export const AgentEnrolmentSchema = z.object({
+  agentId: z.string(),
+  enrolled: z.boolean(),
+  /** True when a person said so, false when it was inferred from a state file. */
+  explicit: z.boolean(),
+});
+
+/**
+ * Everything the composer pill draws itself from, in one round trip.
+ *
+ * `enabled` rides along because it decides whether there is a pill at all: with the
+ * feature switched off there is nothing for one to say, and a pill that read
+ * "paused" would just be a second way of spelling off.
+ */
+export const EnrolmentStateSchema = z.object({
+  showPill: z.boolean(),
+  enabled: z.boolean(),
+  /** Only agents with a state file or an explicit answer. Anyone absent is off. */
+  agents: z.array(AgentEnrolmentSchema),
+});
+export type EnrolmentState = z.infer<typeof EnrolmentStateSchema>;
+
+export const enrolmentState = defineRpc({
+  name: "smart-session.enrolment.state",
+  input: z.object({}),
+  output: EnrolmentStateSchema,
+});
+
+export const setEnrolment = defineRpc({
+  name: "smart-session.enrolment.set",
+  input: z.object({ agentId: z.string(), enrolled: z.boolean() }),
+  output: z.object({ agent: AgentEnrolmentSchema }),
+});
+
+/**
+ * The instructions sent with `/compact`.
+ *
+ * Two jobs. It tells the summarizer what this particular task cannot afford to
+ * lose, and — when the agent named a state file — it points the continuation at the
+ * one thing on disk that is authoritative, so the quality of the summary stops
+ * being load-bearing.
+ */
+export function compactionInstructions(request: {
+  reason: string;
+  statePath: string | null;
+}): string {
+  const parts = [
+    "/compact",
+    `Preserve: the current goal, the step in progress and its exact next action, decisions already made and why, and every approach already tried and rejected.`,
+    `Discard: file contents already read, superseded plans, and tool output that has been acted on.`,
+    `Reason for compacting now: ${request.reason}`,
+  ];
+  if (request.statePath !== null && request.statePath !== "") {
+    parts.push(
+      `Authoritative state lives at ${request.statePath}. Re-read that file before acting; where it disagrees with this summary, the file wins.`,
+    );
+  }
+  return parts.join(" ");
+}
+
+/**
+ * What the continuation is told, once the compaction has landed.
+ *
+ * This is the second and last message Paseo sends, and it exists because no hook
+ * can do it. `PostCompact` cannot inject at all; `SessionStart:compact` injects
+ * context but starts no turn — its `initialUserMessage` field is only ever read at
+ * process startup; and `Stop` does not fire for a `/compact`, because a command
+ * runs no model turn. All three were tested against 2.1.263 (`RESEARCH.md` §3.4).
+ *
+ * Deliberately short. The state file holds the task and the summary holds the
+ * conversation, so restating either here would only give the continuation a third
+ * account to reconcile.
+ */
+export function resumeInstructions(request: { statePath: string | null }): string {
+  if (request.statePath === null || request.statePath === "") {
+    return (
+      "That compaction was the one you asked for. Pick the task back up from the summary above and carry on from the next action it describes — " +
+      "and write your task state to disk with the checkpoint tool now, so the next one costs nothing."
+    );
+  }
+  return (
+    `That compaction was the one you asked for. Re-read ${request.statePath} and continue from its "Current step" section. ` +
+    "Where the file disagrees with the summary above, the file is correct — it was written deliberately; the summary was compressed automatically. " +
+    "Carry on from there without asking what to do next."
+  );
+}
+
+/**
+ * Resolves the optional second message after a queued compaction lands.
+ *
+ * Continuing remains the default for requests made by older plugin versions, but
+ * the requesting agent can suppress the turn when its task is already complete or
+ * replace the state-aware default with the exact next instruction it needs.
+ */
+export function continuationInstructions(request: {
+  continueAfterCompaction: boolean;
+  continuationMessage: string | null;
+  statePath: string | null;
+}): string | null {
+  if (!request.continueAfterCompaction) return null;
+  return request.continuationMessage ?? resumeInstructions({ statePath: request.statePath });
+}

package/shared/lifecycle.ts

@@ -0,0 +1,17 @@
+/**
+ * Lets the entry point release daemon-side resources without naming them.
+ *
+ * Paseo deletes `*.server` imports from the client bundle but keeps the surrounding
+ * statements, so a server identifier in `contribute()`'s shared body becomes a
+ * ReferenceError that aborts every registration. A shared module is safe in both
+ * bundles: `recorder.server` fills this in on the daemon, and it stays null in the
+ * client, where there is nothing to release.
+ */
+export type Teardown = () => void | Promise<void>;
+
+/**
+ * A list rather than a single slot: the recorder and the governor each start on
+ * import and each own a timer, and both must be released or the subprocess never
+ * exits and the plugin wedges at "Stopping" for the life of the daemon.
+ */
+export const lifecycle: { teardowns: Teardown[] } = { teardowns: [] };

package/shared/smart-session.ts

@@ -0,0 +1,155 @@
+/**
+ * RPC contracts, shared by both bundles.
+ *
+ * Zod schemas here are the wire contract: the daemon validates input and output
+ * against them, so a shape change that a client has not seen fails loudly at the
+ * boundary rather than quietly downstream.
+ */
+
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+
+export const WindowStatusSchema = z.object({
+  id: z.string(),
+  pct: z.number(),
+  resetsAt: z.string().nullable(),
+  /** Percentage points per hour over the recent past; null when it cannot be measured. */
+  burnPctPerHour: z.number().nullable(),
+  /** When this window hits 100% at that rate, if that happens before it resets. */
+  projectedFullAt: z.string().nullable(),
+});
+
+export const RecorderStatusSchema = z.object({
+  /** The reading the store considers current, as an instant the provider vouched for. */
+  newestAt: z.string().nullable(),
+  /** How stale that reading is, in seconds. */
+  ageSeconds: z.number().nullable(),
+  source: z.string().nullable(),
+  samplesHeld: z.number(),
+  firstSampleAt: z.string().nullable(),
+  dataDir: z.string(),
+});
+
+/**
+ * Everything an agent or a panel needs to answer "how much budget is left, and how
+ * fast am I spending it".
+ */
+export const budgetStatus = defineRpc({
+  name: "smart-session.budget",
+  input: z.object({}),
+  output: z.object({
+    windows: z.array(WindowStatusSchema),
+    recorder: RecorderStatusSchema,
+    error: z.string().nullable(),
+  }),
+});
+
+export const ContextStatusSchema = z.object({
+  agentId: z.string(),
+  title: z.string().nullable(),
+  provider: z.string(),
+  model: z.string().nullable(),
+  status: z.string(),
+  usedTokens: z.number(),
+  maxTokens: z.number(),
+  usedPct: z.number(),
+  costUsd: z.number().nullable(),
+  /** Recent context growth, from the recorded history. Null until there is a span to measure. */
+  growthTokensPerHour: z.number().nullable(),
+  /** When this agent would reach the compact band, at that rate. */
+  projectedFullAt: z.string().nullable(),
+  /** The percentage at which this window is considered ready to compact. */
+  compactAtPct: z.number(),
+});
+
+/** Context occupancy for one agent, or all of them. */
+export const contextStatus = defineRpc({
+  name: "smart-session.context",
+  input: z.object({ agentId: z.string().optional() }),
+  output: z.object({
+    agents: z.array(ContextStatusSchema),
+    error: z.string().nullable(),
+  }),
+});
+
+
+const ThresholdProfileSchema = z.object({
+  notice: z.number().finite().min(1).max(99),
+  closing: z.number().finite().min(1).max(99),
+  compact: z.number().finite().min(1).max(99),
+});
+
+export const ThresholdsSchema = z.object({
+  largeWindowFrom: z.number().finite().positive(),
+  large: ThresholdProfileSchema,
+  small: ThresholdProfileSchema,
+});
+
+export const SettingsSchema = z.object({
+  /** The master switch: with this off, Smart Compact does nothing at all. */
+  enabled: z.boolean(),
+  thresholds: ThresholdsSchema,
+  freshStateMinutes: z.number(),
+  /** Whether every agent's composer carries the smart-compact pill. */
+  showPill: z.boolean(),
+  /** Whether checkpointing enrols a session, or enrolment is per-session opt-in. */
+  autoEnrol: z.boolean(),
+  /** Whether the plugin keeps its own hooks registered in Claude Code. */
+  installHooks: z.boolean(),
+});
+
+/**
+ * What the plugin did to Claude Code's configuration, and whether it worked.
+ *
+ * Worth surfacing rather than only logging: an install that silently found no
+ * hooks directory looks exactly like a working one from the outside.
+ */
+export const InstallReportSchema = z.object({
+  pluginDir: z.string().nullable(),
+  settingsPath: z.string(),
+  changed: z.boolean(),
+  hooks: z.array(z.string()),
+  mcp: z.enum(["present", "added", "unavailable", "skipped"]),
+  error: z.string().nullable(),
+});
+
+/** The state of the Claude Code integration, re-reconciled on demand. */
+export const installStatus = defineRpc({
+  name: "smart-session.install.status",
+  input: z.object({}),
+  output: z.object({ report: InstallReportSchema }),
+});
+
+/** Read the governor's settings, and the count of agents currently enrolled. */
+export const getSettings = defineRpc({
+  name: "smart-session.settings.get",
+  input: z.object({}),
+  output: z.object({ settings: SettingsSchema, enrolledAgents: z.number() }),
+});
+
+export const setSettings = defineRpc({
+  name: "smart-session.settings.set",
+  input: SettingsSchema.partial(),
+  output: z.object({ settings: SettingsSchema }),
+});
+
+
+export const SpendSummarySchema = z.object({
+  byDay: z.array(z.object({ day: z.string(), tokens: z.number(), messages: z.number() })),
+  heatmap: z.array(z.object({ weekday: z.number(), hour: z.number(), tokens: z.number() })),
+  byProject: z.array(z.object({ name: z.string(), tokens: z.number() })),
+  byModel: z.array(z.object({ name: z.string(), tokens: z.number() })),
+  totalTokens: z.number(),
+  subagentTokens: z.number(),
+  cacheHitPct: z.number(),
+  firstHour: z.string().nullable(),
+  lastHour: z.string().nullable(),
+  bucketCount: z.number(),
+});
+
+/** Token spend reconstructed from transcripts — the history from before the recorder. */
+export const spendSummary = defineRpc({
+  name: "smart-session.spend",
+  input: z.object({ days: z.number().optional() }),
+  output: z.object({ summary: SpendSummarySchema, error: z.string().nullable() }),
+});