paseo-smart-session 1.2.1

package/server/governor.ts

@@ -0,0 +1,288 @@
+/**
+ * Delivery for compaction requests.
+ *
+ * The queue lives on the daemon so a request survives a plugin reload, a Paseo
+ * restart, and the client that made it going away. Delivery waits for the target
+ * agent to be idle, then sends `/compact <instructions>` — which Paseo routes as a
+ * real command rather than as text the model reads.
+ *
+ * This file decides nothing. Every request in the queue was put there by the agent
+ * it belongs to, or by a person; the governor's whole job is to carry it out at a
+ * moment when doing so is safe, and then, when requested, to hand the emptied
+ * session back its state file. Those are the only things this plugin ever says to
+ * an agent.
+ */
+
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { readAgents, sendToAgent, withDaemon, type AgentRow } from "./daemon.ts";
+import { compactionInstructions, continuationInstructions, type CompactionRequest } from "../shared/governor.ts";
+import { lifecycle } from "../shared/lifecycle.ts";
+import { readSettings } from "./settings.ts";
+import { dataDir } from "./store.ts";
+
+const TICK_MS = 15_000;
+
+/**
+ * How long to keep watching an agent after a compaction, to record what it
+ * achieved and to hand it back its state file. Compaction is a summarization turn;
+ * a few minutes of ticks is plenty.
+ */
+const GRADE_WINDOW_MS = 5 * 60_000;
+
+const queuePath = () => join(dataDir(), "compactions.json");
+
+let tail: Promise<unknown> = Promise.resolve();
+
+function serialize<T>(work: () => Promise<T>): Promise<T> {
+  const next = tail.then(work, work);
+  tail = next.then(
+    () => undefined,
+    () => undefined,
+  );
+  return next;
+}
+
+/**
+ * Fills in fields added after a row was written.
+ *
+ * The queue is validated against `CompactionRequestSchema` on its way out over the
+ * RPC boundary, so a row from an older version missing a key would fail there
+ * rather than here. Defaulting on read is the migration.
+ */
+function normalize(item: CompactionRequest): CompactionRequest {
+  return {
+    ...item,
+    continueAfterCompaction: item.continueAfterCompaction ?? true,
+    continuationMessage: item.continuationMessage ?? null,
+    resumedAt: item.resumedAt ?? null,
+  };
+}
+
+async function readAll(): Promise<CompactionRequest[]> {
+  try {
+    const raw = await readFile(queuePath(), "utf8");
+    const parsed = JSON.parse(raw) as { version?: number; items?: CompactionRequest[] };
+    return (parsed.items ?? []).map(normalize);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") console.error("[smart-session] could not read the compaction queue", String(error));
+    return [];
+  }
+}
+
+async function writeAll(items: CompactionRequest[]): Promise<void> {
+  await mkdir(dataDir(), { recursive: true });
+  const target = queuePath();
+  const temp = `${target}.${randomUUID()}.tmp`;
+  await writeFile(temp, JSON.stringify({ version: 1, items }, null, 2), "utf8");
+  await rename(temp, target);
+}
+
+export const queue = {
+  list: (): Promise<CompactionRequest[]> => serialize(readAll),
+
+  add: (input: {
+    agentId: string;
+    reason: string;
+    statePath: string | null;
+    continueAfterCompaction: boolean;
+    continuationMessage: string | null;
+  }): Promise<CompactionRequest> =>
+    serialize(async () => {
+      const items = await readAll();
+      const request: CompactionRequest = {
+        id: randomUUID(),
+        agentId: input.agentId,
+        reason: input.reason,
+        statePath: input.statePath,
+        continueAfterCompaction: input.continueAfterCompaction,
+        continuationMessage: input.continuationMessage,
+        createdAt: new Date().toISOString(),
+        state: "pending",
+        settledAt: null,
+        error: null,
+        preTokens: null,
+        postTokens: null,
+        resumedAt: null,
+      };
+      items.push(request);
+      await writeAll(items);
+      return request;
+    }),
+
+  update: (id: string, patch: Partial<CompactionRequest>): Promise<CompactionRequest | null> =>
+    serialize(async () => {
+      const items = await readAll();
+      const found = items.find((item) => item.id === id);
+      if (found === undefined) return null;
+      Object.assign(found, patch);
+      await writeAll(items);
+      return found;
+    }),
+
+  /**
+   * A request interrupted mid-send is failed, never retried.
+   *
+   * `/compact` is destructive and not idempotent: sending a second one after a
+   * restart could discard a context the first one already summarized. Failing
+   * closed costs one compaction; retrying could cost the task.
+   */
+  recoverInterrupted: (): Promise<number> =>
+    serialize(async () => {
+      const items = await readAll();
+      let count = 0;
+      for (const item of items) {
+        if (item.state !== "sending") continue;
+        item.state = "failed";
+        item.error = "The plugin stopped while sending; not retried, because a second /compact is destructive.";
+        item.settledAt = new Date().toISOString();
+        count += 1;
+      }
+      if (count > 0) await writeAll(items);
+      return count;
+    }),
+};
+
+/**
+ * Agents whose compaction we are still waiting to land.
+ *
+ * Two things happen when it does: the post-compaction size is recorded, so the
+ * policy can be graded, and, if the agent requested it, the emptied session is
+ * sent its chosen continuation. Nothing else will start that turn — see
+ * `continuationInstructions`.
+ */
+const grading = new Map<
+  string,
+  {
+    requestId: string;
+    preTokens: number | null;
+    statePath: string | null;
+    continueAfterCompaction: boolean;
+    continuationMessage: string | null;
+    until: number;
+  }
+>();
+
+async function flush(): Promise<void> {
+  const settings = await readSettings();
+  // The master switch. Off means a queued request waits rather than failing: the
+  // agent asked for it, and turning the feature back on should honour that.
+  if (!settings.enabled) return;
+
+  const pending = (await queue.list()).filter((item) => item.state === "pending");
+  // No queued work and nothing to land means no reason to open a connection.
+  if (pending.length === 0 && grading.size === 0) return;
+
+  await withDaemon(async (client) => {
+    const agents = new Map<string, AgentRow>();
+    for (const agent of await readAgents(client)) agents.set(agent.id, agent);
+
+    // Land compactions that have already happened.
+    for (const [agentId, watch] of [...grading]) {
+      const agent = agents.get(agentId);
+      if (Date.now() > watch.until || agent === undefined) {
+        grading.delete(agentId);
+        continue;
+      }
+      if (agent.status !== "idle" || agent.usedTokens === null) continue;
+      if (watch.preTokens !== null && agent.usedTokens >= watch.preTokens) continue; // Not shrunk yet.
+      await queue.update(watch.requestId, { postTokens: agent.usedTokens });
+      grading.delete(agentId);
+
+      const continuation = continuationInstructions(watch);
+      if (continuation === null) {
+        console.log(`[smart-session] compacted ${agentId.slice(0, 8)} without a continuation, as requested`);
+        continue;
+      }
+
+      // A manual /compact leaves the session idle with the task abandoned: no hook
+      // fires afterwards that can start a turn. Send one only when the requesting
+      // agent explicitly or implicitly chose to continue.
+      try {
+        await sendToAgent(client, agentId, continuation);
+        await queue.update(watch.requestId, { resumedAt: new Date().toISOString() });
+        console.log(`[smart-session] sent ${agentId.slice(0, 8)} its continuation after compacting`);
+      } catch (error) {
+        // The compaction itself succeeded; failing to restart the task is worth a
+        // line in the log, not a failed request.
+        console.error(`[smart-session] could not continue ${agentId.slice(0, 8)}`, String(error));
+      }
+    }
+
+    for (const item of pending) {
+      const agent = agents.get(item.agentId);
+      if (agent === undefined || agent.status === "closed") {
+        await queue.update(item.id, {
+          state: "failed",
+          error: "The target session is gone.",
+          settledAt: new Date().toISOString(),
+        });
+        continue;
+      }
+      // Sending into a live turn steers it instead of arriving as its own
+      // instruction, and compacting mid-turn discards exactly the working state the
+      // agent has not written down yet. Wait for the next tick instead.
+      if (agent.status !== "idle") continue;
+
+      // Claim before sending, so a crash cannot produce a second /compact.
+      const claimed = await queue.update(item.id, { state: "sending", preTokens: agent.usedTokens });
+      try {
+        await sendToAgent(client, item.agentId, compactionInstructions(claimed ?? item));
+        await queue.update(item.id, { state: "sent", settledAt: new Date().toISOString() });
+        grading.set(item.agentId, {
+          requestId: item.id,
+          preTokens: agent.usedTokens,
+          statePath: item.statePath,
+          continueAfterCompaction: item.continueAfterCompaction,
+          continuationMessage: item.continuationMessage,
+          until: Date.now() + GRADE_WINDOW_MS,
+        });
+        console.log(`[smart-session] compacted ${item.agentId.slice(0, 8)} (${item.reason})`);
+      } catch (error) {
+        await queue.update(item.id, {
+          state: "failed",
+          error: error instanceof Error ? error.message : String(error),
+          settledAt: new Date().toISOString(),
+        });
+      }
+    }
+  });
+}
+
+function startGovernor(): void {
+  let running = false;
+  let stopped = false;
+
+  const tick = async () => {
+    if (running || stopped) return;
+    running = true;
+    try {
+      await flush();
+    } catch (error) {
+      console.error("[smart-session] governor tick failed", String(error));
+    } finally {
+      running = false;
+    }
+  };
+
+  void queue
+    .recoverInterrupted()
+    .then((count) => {
+      if (count > 0) console.error(`[smart-session] failed ${count} compaction(s) interrupted by a restart`);
+    })
+    .catch((error: unknown) => console.error("[smart-session] recovery failed", String(error)))
+    .then(tick);
+
+  const timer = setInterval(() => void tick(), TICK_MS);
+
+  lifecycle.teardowns.push(() => {
+    stopped = true;
+    clearInterval(timer);
+    grading.clear();
+  });
+}
+
+startGovernor();

package/server/growth.ts

@@ -0,0 +1,67 @@
+/**
+ * Context growth, measured from recorded history.
+ *
+ * Lives in the server runtime rather than in the entry so its history and
+ * filesystem dependencies can never cross into the client bundle.
+ */
+
+import { readContext } from "./store.ts";
+import { profileFor, type Thresholds } from "../shared/thresholds.ts";
+
+/**
+ * How fast each agent's context is filling, in tokens per hour.
+ *
+ * Measured from what the recorder has actually seen rather than from the agent's
+ * own bookkeeping: a rate is only meaningful over a span, and the span has to come
+ * from somewhere that survives the turn.
+ */
+export async function contextGrowth(): Promise<Map<string, number>> {
+  const MEASURE_MS = 2 * 60 * 60 * 1000;
+  const MIN_SPAN_MS = 5 * 60 * 1000;
+  const rows = await readContext({ sinceMs: Date.now() - MEASURE_MS });
+
+  const byAgent = new Map<string, { firstAt: number; firstTokens: number; lastAt: number; lastTokens: number }>();
+  for (const row of rows) {
+    const at = Date.parse(row.at);
+    const seen = byAgent.get(row.agentId);
+    if (seen === undefined) {
+      byAgent.set(row.agentId, { firstAt: at, firstTokens: row.usedTokens, lastAt: at, lastTokens: row.usedTokens });
+      continue;
+    }
+    // A compaction resets the baseline: growth measured across one would be
+    // negative and meaningless, so start again from the drop.
+    if (row.usedTokens < seen.lastTokens) {
+      byAgent.set(row.agentId, { firstAt: at, firstTokens: row.usedTokens, lastAt: at, lastTokens: row.usedTokens });
+      continue;
+    }
+    seen.lastAt = at;
+    seen.lastTokens = row.usedTokens;
+  }
+
+  const rates = new Map<string, number>();
+  for (const [agentId, span] of byAgent) {
+    const ms = span.lastAt - span.firstAt;
+    if (ms < MIN_SPAN_MS) continue;
+    rates.set(agentId, ((span.lastTokens - span.firstTokens) / ms) * 3_600_000);
+  }
+  return rates;
+}
+
+/**
+ * When an agent's context would reach the point where compacting is the right call.
+ *
+ * Aimed at the window's own compact band, not at its ceiling: on a large window the
+ * ceiling is never what bites first, so projecting to 100% would forecast a moment
+ * nobody should ever reach.
+ */
+export function projectFull(
+  usedTokens: number,
+  maxTokens: number,
+  ratePerHour: number | null,
+  thresholds?: Thresholds,
+): string | null {
+  if (ratePerHour === null || ratePerHour <= 0) return null;
+  const room = maxTokens * (profileFor(maxTokens, thresholds).compact / 100) - usedTokens;
+  if (room <= 0) return new Date().toISOString();
+  return new Date(Date.now() + (room / ratePerHour) * 3_600_000).toISOString();
+}

package/server/install-on-load.ts

@@ -0,0 +1,34 @@
+/**
+ * Reconciling Claude Code's configuration, once, when the plugin loads.
+ *
+ * A separate module from `install.server.ts` for two reasons, and both of them
+ * matter more than the four lines saved by merging them.
+ *
+ * Paseo compiles the server entry independently, so the load-time side effect
+ * belongs here and is imported only by `index.server.ts`. `check-bundles.mjs`
+ * guards that runtime boundary.
+ *
+ * And it keeps `install.server.ts` free of side effects, so a test can import the
+ * reconciler without a module-level call racing it — or worse, writing to the
+ * machine's real Claude Code settings just because something imported a function.
+ */
+
+import { install } from "./install.ts";
+
+void install()
+  .then((report) => {
+    if (report.error !== null) {
+      console.error(`[smart-session] ${report.error}`);
+      return;
+    }
+    if (report.changed) {
+      console.log(`[smart-session] registered ${report.hooks.join(", ")} in ${report.settingsPath}`);
+    }
+    if (report.mcp === "added") console.log("[smart-session] registered the agent-facing MCP server");
+    if (report.mcp === "unavailable") {
+      console.error(
+        "[smart-session] could not reach the `claude` CLI to register the MCP server; run `claude mcp add-json --scope user smart-session` by hand if the agent tools are missing",
+      );
+    }
+  })
+  .catch((error: unknown) => console.error("[smart-session] hook install failed", String(error)));