paseo-smart-session 2.0.0 → 2.2.0

package/server/guard/store.ts

@@ -0,0 +1,113 @@
+import { mkdir, readFile, rename, open, unlink, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { StateSchema, type State } from "../../shared/guard/policy.ts";
+
+/**
+ * Where Session Guard keeps its pauses, session overrides and governor lock.
+ *
+ * Deliberately the standalone `paseo-session-guard` plugin's directory, not
+ * `plugin-data/smart-session/`. Both plugins may be installed on one host while people
+ * move over, and both would otherwise pause the same agent. Sharing this directory
+ * means they share `governor.lock`, so exactly one of them governs; and when the
+ * standalone plugin is removed, its per-session choices and confirmed waits are picked
+ * up here instead of being lost. The state shape is therefore frozen: the standalone
+ * plugin reads and rewrites the same file, and its schema would strip anything new.
+ */
+export function guardDataDir(): string {
+  return join(process.env.PASEO_HOME ?? join(homedir(), ".paseo"), "plugin-data", "session-guard");
+}
+
+/** A live process already governs this host. Not a failure: the caller defers to it. */
+export class LockHeldError extends Error {}
+
+export class Store {
+  readonly directory: string;
+  constructor(directory: string) { this.directory = directory; }
+  async read(): Promise<State> {
+    try {
+      return StateSchema.parse(JSON.parse(await readFile(join(this.directory, "state.json"), "utf8")));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 1, overrides: {}, pauses: [] };
+      throw new Error("Session Guard state could not be read. Restore state.json before continuing.");
+    }
+  }
+  async write(state: State): Promise<void> {
+    const parsed = StateSchema.parse(state);
+    // Keep pending work and a bounded history; never write transcripts or prompts.
+    const pending = parsed.pauses.filter(p => p.settledAt === null);
+    const history = parsed.pauses.filter(p => p.settledAt !== null).slice(-200);
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const temporary = join(this.directory, `state-${randomUUID()}.tmp`);
+    try {
+      const file = await open(temporary, "wx", 0o600);
+      try {
+        await file.writeFile(JSON.stringify({ ...parsed, pauses: [...history, ...pending] }, null, 2));
+        await file.sync(); // Confirmed schedules must reach disk before signals.
+      } finally { await file.close(); }
+      await rename(temporary, join(this.directory, "state.json"));
+      if (process.platform === "linux") {
+        const directory = await open(this.directory, "r");
+        try { await directory.sync(); } finally { await directory.close(); }
+      }
+    } finally { await unlink(temporary).catch(() => undefined); }
+  }
+  /** One governor per host, including installs under a second plugin ID. */
+  async lock(): Promise<() => Promise<void>> {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const path = join(this.directory, "governor.lock");
+    const identity = async (pid: number) => {
+      if (process.platform !== "linux") return null;
+      const boot = (await readFile("/proc/sys/kernel/random/boot_id", "utf8")).trim();
+      const raw = await readFile(`/proc/${pid}/stat`, "utf8");
+      const birth = raw.slice(raw.lastIndexOf(")") + 2).trim().split(/\s+/)[19];
+      return `${boot}:${birth}`;
+    };
+    const token = `${process.pid}:${randomUUID()}:${await identity(process.pid) ?? "portable"}`;
+    const alive = async (value: string) => {
+      const [pidText, , ...saved] = value.split(":"); const pid = Number(pidText);
+      if (!Number.isInteger(pid) || pid <= 0) throw new Error("Governor lock has an invalid owner.");
+      try {
+        process.kill(pid, 0);
+        return saved.length < 2 || process.platform !== "linux" || await identity(pid) === saved.join(":");
+      } catch (error) {
+        if (["ESRCH", "ENOENT"].includes((error as NodeJS.ErrnoException).code ?? "")) return false;
+        throw error;
+      }
+    };
+    const claim = async () => {
+      const handle = await open(path, "wx", 0o600);
+      try { await handle.writeFile(token); } finally { await handle.close(); }
+    };
+    try { await claim(); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      const previous = await readFile(path, "utf8");
+      if (await alive(previous)) throw new LockHeldError("Another Session Guard instance is already running.");
+      // Stale-lock recovery must itself be exclusive across simultaneous loads.
+      const recoveryPath = `${path}.recovery`;
+      const abandoned = await readFile(recoveryPath, "utf8").catch(error => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (abandoned !== null) {
+        // Older releases left an empty recovery file. Allow its writer time to
+        // finish; a nonempty owner is checked by boot and process birth identity.
+        const expired = abandoned === "" ? Date.now() - (await stat(recoveryPath)).mtimeMs > 30_000 : !await alive(abandoned);
+        if (!expired) throw new LockHeldError("Governor recovery is already running.");
+        if (await readFile(recoveryPath, "utf8") !== abandoned) throw new Error("Governor recovery changed.");
+        await unlink(recoveryPath);
+      }
+      const recovery = await open(recoveryPath, "wx", 0o600);
+      await recovery.writeFile(token);
+      try {
+        if (await readFile(path, "utf8") !== previous) throw new Error("Governor lock changed; reload Session Guard.");
+        await unlink(path);
+        await claim();
+      } finally { await recovery.close(); await unlink(`${path}.recovery`).catch(() => undefined); }
+    }
+    return async () => {
+      if (await readFile(path, "utf8").catch(() => null) === token) await unlink(path);
+    };
+  }
+}

package/server/guard/timeline.ts

@@ -0,0 +1,24 @@
+import type { PluginHandlerContext } from "@getpaseo/plugin/server";
+import type { Notification } from "../../shared/guard/timeline.ts";
+
+export type PublishTimeline = (agentId: string, notification: Notification, reconcile: boolean) => Promise<void>;
+export function timelinePublisher(api: () => Promise<PluginHandlerContext["paseo"]>): PublishTimeline {
+  return async (agentId, notification, reconcile) => {
+    const timeline = (await api()).agents.ref(agentId).timeline;
+    if (reconcile) {
+      // Lost acknowledgements are checked against durable history before retry.
+      // Only IDs/timestamps are inspected; content is never logged or retained.
+      let cursor: NonNullable<Parameters<typeof timeline.refetch>[0]>["cursor"];
+      for (let page = 0; page < 32; page++) {
+        const result = await timeline.refetch({ direction: cursor ? "before" : "tail", ...(cursor ? { cursor } : {}), limit: 100, projection: "canonical" });
+        if (result.error || result.staleCursor) throw new Error("Timeline receipt could not be checked.");
+        if (result.entries.some(entry => entry.item.type === "plugin" && entry.item.id === notification.id)) return;
+        if (!result.hasOlder || result.entries.some(entry => Date.parse(entry.timestamp) < Date.parse(notification.data.at))) break;
+        if (!result.startCursor) throw new Error("Timeline receipt cursor is unavailable.");
+        cursor = result.startCursor;
+        if (page === 31) throw new Error("Timeline receipt check exceeded its page budget.");
+      }
+    }
+    await timeline.append({ type: "plugin", id: notification.id, kind: "quota-pause", version: 1, data: notification.data });
+  };
+}

package/server/guard/usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Session Guard's usage reading, sharpened with Smart Session's recorder.
+ *
+ * The guard needs every provider's session window, which only Paseo's
+ * `provider.usage.list` reports. For Claude, though, Paseo serves a cache up to five
+ * minutes old and cannot be made to refresh (RESEARCH.md §7a), while the recorder in
+ * this same process asks Anthropic directly every three minutes. Whichever reading is
+ * newer wins, so a pause and — more usefully — its release follow the fresher number
+ * instead of waiting out Paseo's cache.
+ *
+ * Only a reading that says when the provider produced it is used: `resetReady` trusts
+ * `fetchedAt` to prove a report is newer than the pause, and an observation time is not
+ * that.
+ */
+
+import { canonicalWindowId, effectiveAt, type UsageSample } from "../../shared/usage.ts";
+import type { ProviderUsage, Usage, UsageWindow } from "../../shared/guard/policy.ts";
+
+/** The provider the recorder measures. It records nothing for any other. */
+const RECORDED_PROVIDER = "claude";
+
+export function withRecordedUsage(paseo: Usage, recorded: UsageSample | null): Usage {
+  if (recorded === null || recorded.fetchedAt === null) return paseo;
+  const recordedMs = Date.parse(effectiveAt(recorded));
+  if (!Number.isFinite(recordedMs)) return paseo;
+
+  const index = paseo.providers.findIndex((provider) => provider.providerId === RECORDED_PROVIDER);
+  const current = index === -1 ? undefined : paseo.providers[index];
+  if (current?.status === "available") {
+    const paseoMs = Date.parse(current.fetchedAt ?? paseo.fetchedAt);
+    if (Number.isFinite(paseoMs) && paseoMs >= recordedMs) return paseo;
+  }
+
+  // Keep Paseo's window ids, which are what the policy's `windowIds` name, and fill
+  // them from the recorder; the recorder's own canonical ids cover any it lacks.
+  const used = new Set<string>();
+  const windows: UsageWindow[] = [];
+  for (const window of current?.status === "available" ? current.windows : []) {
+    const id = canonicalWindowId(window.id);
+    const reading = recorded.windows[id];
+    if (reading === undefined) {
+      windows.push(window);
+      continue;
+    }
+    used.add(id);
+    windows.push({ id: window.id, usedPct: reading.pct, remainingPct: null, resetsAt: reading.resetsAt ?? window.resetsAt ?? null });
+  }
+  for (const [id, reading] of Object.entries(recorded.windows)) {
+    if (!used.has(id)) windows.push({ id, usedPct: reading.pct, remainingPct: null, resetsAt: reading.resetsAt });
+  }
+
+  const merged: ProviderUsage = { providerId: RECORDED_PROVIDER, status: "available", fetchedAt: new Date(recordedMs).toISOString(), windows };
+  const providers = [...paseo.providers];
+  if (index === -1) providers.push(merged);
+  else providers[index] = merged;
+  return { ...paseo, providers };
+}

package/server/recorder.ts

@@ -22,6 +22,7 @@ import {
   appendUsage,
   clearCaches,
   newestUsage,
+  noteAcceptedReading,
   noteNewestUsage,
   type ContextSample,
 } from "./store.ts";
@@ -86,6 +87,7 @@ async function record(sample: UsageSample): Promise<boolean> {
   const newest = await newestUsage();
   const verdict = acceptReading(newest, sample);
   if (!verdict.ok) return false;
+  noteAcceptedReading(sample);
   if (!isWorthRecording(newest, sample)) return false;
   await appendUsage(sample);
   noteNewestUsage(sample);

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/server/store.ts

@@ -12,7 +12,7 @@ import { appendFile, mkdir, readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import type { UsageSample } from "../shared/usage.ts";
+import { effectiveAt, type UsageSample } from "../shared/usage.ts";
 
 const DATA_DIRECTORY = "smart-session";
 const LEGACY_DATA_DIRECTORY = "super-session";
@@ -195,7 +195,31 @@ export function noteNewestUsage(sample: UsageSample): void {
   newestCache = { value: sample };
 }
 
+/**
+ * The newest reading that passed the acceptance gate, whether or not it was written.
+ *
+ * Most readings are refused by `isWorthRecording` only because nothing moved, so the
+ * newest *line* can be minutes older than the newest *fact*. Session Guard wants the
+ * fact — a fresh report below its threshold is what confirms a reset.
+ */
+let latestAccepted: UsageSample | null = null;
+
+export function noteAcceptedReading(sample: UsageSample): void {
+  if (latestAccepted === null || Date.parse(effectiveAt(sample)) >= Date.parse(effectiveAt(latestAccepted))) {
+    latestAccepted = sample;
+  }
+}
+
+/** The freshest Claude plan-usage reading this process knows of, recorded or not. */
+export async function freshestUsage(): Promise<UsageSample | null> {
+  const newest = await newestUsage();
+  if (latestAccepted === null) return newest;
+  if (newest === null) return latestAccepted;
+  return Date.parse(effectiveAt(latestAccepted)) >= Date.parse(effectiveAt(newest)) ? latestAccepted : newest;
+}
+
 /** Drops in-memory state so a reload starts clean. */
 export function clearCaches(): void {
   newestCache = null;
+  latestAccepted = null;
 }

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;
+}