paseo-smart-session 1.2.1

package/hooks/pointer.mjs

@@ -0,0 +1,149 @@
+/**
+ * The state-file pointer, and the two ways it can reach the model.
+ *
+ * Compaction is the one moment the agent is deciding what it knows, so it is the
+ * one moment worth spending an injection on. But `PostCompact` — the event that
+ * knows a compaction happened — cannot inject: Claude Code validates
+ * `hookSpecificOutput.hookEventName` against a union that does not contain it, and
+ * rejects the whole output. So the pointer is written here as a small pending note
+ * and delivered by whichever hook speaks first:
+ *
+ *   - `SessionStart` with `source: "compact"`, which fires in the emptied context
+ *     and does accept `additionalContext`; or
+ *   - the next `PostToolUse`, which is guaranteed to run.
+ *
+ * Whoever delivers it clears it, so it is said exactly once.
+ *
+ * Keyed by Paseo agent id when there is one, because that survives compaction
+ * whatever Claude Code decides to do with the session id.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export function pluginDir() {
+  const home = process.env.PASEO_HOME ?? join(homedir(), ".paseo");
+  return join(home, "plugin-data", "smart-session");
+}
+
+/** The same derivation the agent's `checkpoint` tool uses. */
+export function statePath() {
+  const override = process.env.SMART_SESSION_STATE_FILE;
+  if (override !== undefined && override !== "") return override;
+  const agentId = process.env.PASEO_AGENT_ID;
+  if (agentId === undefined || agentId === "") return null;
+  return join(pluginDir(), "state", `${agentId}.md`);
+}
+
+/** Seconds since the state file was last written, or null if there isn't one. */
+export function stateAgeSeconds(path) {
+  if (path === null || !existsSync(path)) return null;
+  try {
+    return Math.round((Date.now() - statSync(path).mtimeMs) / 1000);
+  } catch {
+    return null;
+  }
+}
+
+const STALE_AFTER_SECONDS = 30 * 60;
+
+/**
+ * What the continuation needs to hear, given what is actually on disk.
+ *
+ * Returns null when there is nowhere to point — no agent id, no override — since
+ * naming no file at all would be worse than silence.
+ */
+export function pointerText(path = statePath(), age = stateAgeSeconds(path)) {
+  if (path === null) return null;
+  if (age === null) {
+    return (
+      `No durable state file exists yet for this session (expected at ${path}). Everything not in the summary above is now gone. ` +
+      "Before continuing, write down the goal, the step in progress and its exact next action, decisions made and why, and every approach already tried and rejected — then keep it current, so the next compaction costs nothing."
+    );
+  }
+  const lines = [
+    `Durable task state for this session is at ${path}. Re-read it before acting. Where it disagrees with the summary above, the file is correct — it was written deliberately; the summary was compressed automatically.`,
+  ];
+  // A state file older than the work it is supposed to describe is worse than
+  // none, because it reads as authoritative. Say so plainly.
+  if (age > STALE_AFTER_SECONDS) {
+    lines.push(
+      `Note: that file was last written ${Math.round(age / 60)} minutes ago, so it may predate recent work. Reconcile it against the summary and update it before continuing.`,
+    );
+  }
+  return lines.join(" ");
+}
+
+function pointerPath(sessionId) {
+  const agentId = process.env.PASEO_AGENT_ID;
+  const key = agentId !== undefined && agentId !== "" ? agentId : sessionId;
+  if (typeof key !== "string" || key === "") return null;
+  return join(pluginDir(), "pointers", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
+}
+
+function readNote(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeNote(sessionId, note) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    mkdirSync(join(pluginDir(), "pointers"), { recursive: true });
+    writeFileSync(path, JSON.stringify(note), "utf8");
+  } catch {
+    // A hook that cannot persist its note must still not break the turn.
+  }
+}
+
+/** Leaves the pointer where either delivery path will find it. */
+export function writePending(sessionId, text) {
+  if (text === null) return;
+  writeNote(sessionId, { at: new Date().toISOString(), text });
+}
+
+/**
+ * Records that the pointer has already reached the model for this compaction.
+ *
+ * Measured on a real compaction: `SessionStart:compact` fires ~55ms *before*
+ * `PostCompact`, so without this the later event would queue a note that the next
+ * tool call repeats. The marker is left in place rather than deleted — the next
+ * compaction overwrites it, and an absent file has to keep meaning "nothing
+ * pending".
+ */
+export function markDelivered(sessionId) {
+  writeNote(sessionId, { at: new Date().toISOString(), delivered: true });
+}
+
+/** Whether this compaction's pointer was already said, within `withinMs`. */
+export function deliveredRecently(sessionId, withinMs) {
+  const note = readNote(sessionId);
+  if (note?.delivered !== true) return false;
+  const at = Date.parse(note.at ?? "");
+  return Number.isFinite(at) && Date.now() - at < withinMs;
+}
+
+/** The pending pointer, without consuming it — nothing is cleared until it is said. */
+export function readPending(sessionId) {
+  const note = readNote(sessionId);
+  if (note === null || note.delivered === true) return null;
+  return typeof note.text === "string" && note.text !== "" ? note.text : null;
+}
+
+/** Called only once the pointer has actually been written to stdout. */
+export function clearPending(sessionId) {
+  const path = pointerPath(sessionId);
+  if (path === null) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // A stale note costs one repeated sentence, never a failed turn.
+  }
+}

package/hooks/post-compact.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * The compaction hook, registered on two events because neither one can do the
+ * whole job.
+ *
+ * `PostCompact` is the event that knows a compaction happened and carries the
+ * summary and its trigger — but Claude Code's hook-output schema has no
+ * `PostCompact` variant, so anything it returns in `hookSpecificOutput` is
+ * rejected wholesale and injects nothing. It is used here for what it can do:
+ * record the compaction, reset the threshold latch so the warnings are available
+ * again in the emptied window, and leave the state-file pointer pending.
+ *
+ * `SessionStart` with `source: "compact"` runs in the fresh context and *does*
+ * accept `additionalContext`, so it delivers the pointer. If it never fires, the
+ * `PostToolUse` threshold hook delivers the same note on the next tool call.
+ * Either way it is said exactly once — see hooks/pointer.mjs.
+ */
+
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  clearPending,
+  deliveredRecently,
+  markDelivered,
+  pluginDir,
+  pointerText,
+  stateAgeSeconds,
+  statePath,
+  writePending,
+} from "./pointer.mjs";
+import { resetLedger } from "./asks.mjs";
+
+/**
+ * How recently SessionStart must have spoken for PostCompact to stay quiet.
+ *
+ * The two events are milliseconds apart for the same compaction; anything on this
+ * scale separates "already said" from a genuinely new one.
+ */
+const SAME_COMPACTION_MS = 120_000;
+
+function resetLatch(sessionId) {
+  if (typeof sessionId !== "string") return;
+  const path = join(pluginDir(), "thresholds", `${sessionId}.json`);
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // A stale latch only costs a missed warning; never fail the turn over it.
+  }
+}
+
+/** Records what compaction cost, so the policy can be graded later. */
+function recordCompaction(event, eventName, age) {
+  try {
+    const dir = pluginDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "compaction-events.jsonl"),
+      `${JSON.stringify({
+        at: new Date().toISOString(),
+        event: eventName,
+        sessionId: event.session_id ?? null,
+        agentId: process.env.PASEO_AGENT_ID ?? null,
+        trigger: event.trigger ?? event.source ?? null,
+        summaryChars: typeof event.compact_summary === "string" ? event.compact_summary.length : null,
+        statePath: statePath(),
+        stateAgeSeconds: age,
+      })}\n`,
+      { flag: "a" },
+    );
+  } catch {
+    // Bookkeeping must never break the turn it is describing.
+  }
+}
+
+/**
+ * Which event this invocation is, without trusting a single field.
+ *
+ * `hook_event_name` is authoritative when present; the payload shape decides
+ * otherwise, since only `SessionStart` carries `source`.
+ */
+function eventNameOf(event) {
+  if (typeof event.hook_event_name === "string") return event.hook_event_name;
+  return typeof event.source === "string" ? "SessionStart" : "PostCompact";
+}
+
+async function main() {
+  const raw = await new Promise((resolve) => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (input += chunk));
+    process.stdin.on("end", () => resolve(input));
+  });
+
+  let event;
+  try {
+    event = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const eventName = eventNameOf(event);
+  // Every other way a session starts — startup, clear, resume, fork — has its own
+  // context and its own reasons; only compaction just destroyed something.
+  if (eventName === "SessionStart" && event.source !== "compact") return;
+
+  const sessionId = event.session_id;
+  const path = statePath();
+  const age = stateAgeSeconds(path);
+  const text = pointerText(path, age);
+
+  resetLatch(sessionId);
+  // A new epoch: the occupancy the last ask was about no longer exists, so a
+  // session that fills up again is entitled to be asked again.
+  resetLedger(sessionId);
+  recordCompaction(event, eventName, age);
+
+  if (eventName !== "SessionStart") {
+    // PostCompact cannot speak. Leave the note for whoever can — unless
+    // SessionStart already said it moments ago for this same compaction.
+    if (!deliveredRecently(sessionId, SAME_COMPACTION_MS)) writePending(sessionId, text);
+    return;
+  }
+
+  if (text === null) return;
+  clearPending(sessionId);
+  markDelivered(sessionId);
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: text },
+      suppressOutput: true,
+    })}\n`,
+  );
+}
+
+void main();

package/index.client.tsx

@@ -0,0 +1,42 @@
+import type { PluginClientContext } from "@getpaseo/plugin/client";
+
+import { contributeClient, refreshPills } from "./client/pill";
+import { SmartSessionSurface } from "./client/surface";
+import { enrolmentState } from "./shared/governor";
+import { getSettings, setSettings } from "./shared/smart-session";
+
+export default function contribute(client: PluginClientContext) {
+  client.addSurface("overview", SmartSessionSurface);
+  client.addSidebarItem({
+    id: "smart-session",
+    title: "Smart Session",
+    icon: "Gauge",
+    surface: "overview",
+  });
+
+  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, {}));
+    },
+  });
+
+  return contributeClient(client);
+}

package/index.server.ts

@@ -0,0 +1,195 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+
+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 { dataDir, newestUsage, readUsage } from "./server/store.ts";
+import {
+  budgetStatus,
+  contextStatus,
+  getSettings,
+  installStatus,
+  setSettings,
+  spendSummary,
+} from "./shared/smart-session.ts";
+
+import {
+  cancelCompaction,
+  enrolmentState,
+  listCompactions,
+  requestCompaction,
+  setEnrolment,
+} from "./shared/governor.ts";
+import { burnRatePctPerHour, projectedExhaustion, segmentBlocks } from "./shared/blocks.ts";
+import { lifecycle } from "./shared/lifecycle.ts";
+import { profileFor } from "./shared/thresholds.ts";
+import { effectiveAt } from "./shared/usage.ts";
+
+// Importing the recorder for its side effect: it starts on load and records
+// whether or not anything is looking at it. See server/recorder.ts.
+import "./server/recorder.ts";
+// Same: the governor owns the compaction queue and its delivery timer.
+import { queue } from "./server/governor.ts";
+// Same again: this one registers the plugin's hooks with Claude Code on load. The
+// `Stop` hook is what asks a session to compact itself, so an install without it
+// reports "on" and does nothing at all.
+import "./server/install-on-load.ts";
+
+export default function contribute(server: PluginServerContext) {
+  server.handle(budgetStatus, async () => {
+    try {
+      const since = Date.now() - 14 * 24 * 60 * 60 * 1000;
+      const samples = await readUsage({ sinceMs: since });
+      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 windows = [...open.values()]
+        .map((block) => ({
+          id: block.windowId,
+          pct: block.finalPct,
+          resetsAt: block.resetsAt,
+          burnPctPerHour: burnRatePctPerHour(block),
+          projectedFullAt: projectedExhaustion(block),
+        }))
+        .sort((a, b) => b.pct - a.pct);
+
+      const newestInstant = newest === null ? null : effectiveAt(newest);
+      return {
+        windows,
+        recorder: {
+          newestAt: newestInstant,
+          ageSeconds:
+            newestInstant === null ? null : Math.round((Date.now() - Date.parse(newestInstant)) / 1000),
+          source: newest?.src ?? null,
+          samplesHeld: samples.length,
+          firstSampleAt: samples.length === 0 ? null : effectiveAt(samples[0]!),
+          dataDir: dataDir(),
+        },
+        error: null,
+      };
+    } catch (error) {
+      return {
+        windows: [],
+        recorder: {
+          newestAt: null,
+          ageSeconds: null,
+          source: null,
+          samplesHeld: 0,
+          firstSampleAt: null,
+          dataDir: dataDir(),
+        },
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+
+  server.handle(contextStatus, async ({ agentId }) => {
+    try {
+      const rows = await withDaemon((client) => readAgents(client));
+      const growth = await contextGrowth();
+      const { thresholds } = await readSettings();
+      const agents = rows
+        .filter((row) => agentId === undefined || row.id === agentId)
+        .filter((row) => row.usedTokens !== null && row.maxTokens !== null && row.maxTokens > 0)
+        .map((row) => ({
+          agentId: row.id,
+          title: row.title,
+          provider: row.provider,
+          model: row.model,
+          status: row.status,
+          usedTokens: row.usedTokens!,
+          maxTokens: row.maxTokens!,
+          usedPct: Math.round((row.usedTokens! / row.maxTokens!) * 1000) / 10,
+          costUsd: row.costUsd,
+          growthTokensPerHour: growth.get(row.id) ?? null,
+          projectedFullAt: projectFull(row.usedTokens!, row.maxTokens!, growth.get(row.id) ?? null, thresholds),
+          compactAtPct: profileFor(row.maxTokens!, thresholds).compact,
+        }))
+        .sort((a, b) => b.usedPct - a.usedPct);
+      return { agents, error: null };
+    } catch (error) {
+      return { agents: [], error: error instanceof Error ? error.message : String(error) };
+    }
+  });
+
+  server.handle(spendSummary, async ({ days }) => {
+    try {
+      return { summary: await summarizeSpend({ days }), error: null };
+    } catch (error) {
+      return {
+        summary: {
+          byDay: [], heatmap: [], byProject: [], byModel: [],
+          totalTokens: 0, subagentTokens: 0, cacheHitPct: 0,
+          firstHour: null, lastHour: null, bucketCount: 0,
+        },
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  });
+
+  server.handle(getSettings, async () => ({
+    settings: await readSettings(),
+    enrolledAgents: await countEnrolled(),
+  }));
+
+  server.handle(setSettings, async (patch) => {
+    const settings = await writeSettings(patch);
+    // Reconciled here as well as on load, so turning the switch off removes the
+    // hooks immediately rather than at the next reload.
+    if (patch.installHooks !== undefined) void install().catch(() => undefined);
+    return { settings };
+  });
+
+  server.handle(installStatus, async () => ({ report: await install() }));
+
+  server.handle(
+    requestCompaction,
+    async ({ agentId, reason, statePath, continueAfterCompaction, continuationMessage }) => ({
+      request: await queue.add({
+        agentId,
+        reason,
+        statePath: statePath ?? null,
+        continueAfterCompaction: continueAfterCompaction ?? true,
+        continuationMessage: continueAfterCompaction === false ? null : (continuationMessage ?? null),
+      }),
+    }),
+  );
+
+  server.handle(listCompactions, async ({ agentId }) => {
+    const items = await queue.list();
+    return {
+      items: (agentId === undefined ? items : items.filter((item) => item.agentId === agentId)).sort(
+        (a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt),
+      ),
+    };
+  });
+
+  server.handle(cancelCompaction, async ({ id }) => {
+    const updated = await queue.update(id, {
+      state: "cancelled",
+      settledAt: new Date().toISOString(),
+    });
+    return { ok: updated !== null };
+  });
+
+  server.handle(enrolmentState, async () => {
+    const settings = await readSettings();
+    return { showPill: settings.showPill, enabled: settings.enabled, agents: await listEnrolment() };
+  });
+
+  server.handle(setEnrolment, async ({ agentId, enrolled }) => ({
+    agent: await setEnrolled(agentId, enrolled),
+  }));
+
+  // The recorder and governor register their timers in this shared lifecycle.
+  // Paseo waits for this cleanup before stopping the plugin subprocess.
+  return async () => {
+    const teardowns = lifecycle.teardowns.splice(0);
+    for (const teardown of teardowns) await teardown();
+  };
+}