paseo-smart-session 3.4.0 → 3.6.0

package/hooks/ask.mjs

@@ -0,0 +1,198 @@
+/**
+ * Smart Compact's question, shared by the two hooks that put it.
+ *
+ * There are two lines per window. Past the lower one, `ask-compact.mjs` on `Stop`
+ * asks at the end of a turn, when it is convenient. Past the upper one,
+ * `context-threshold.mjs` on `PostToolUse` asks right away, mid-turn, because a
+ * session that far along should not start anything new before compacting. Both
+ * read the same settings, the same enrolment, the same queue and the same ledger,
+ * and the guards live here so the two can never disagree about whether to speak.
+ *
+ * Either way the plugin only asks. The agent answers with its own tool call, and
+ * a queued compaction is still delivered once the session goes idle.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { forTools, isEnrolled, occupancy, readSettings } from "./context.mjs";
+import { fileURLToPath } from "node:url";
+import { dirname as parentOf } from "node:path";
+
+/** The one-call bridge a detached session is pointed at (beside this plugin's hooks). */
+export const BRIDGE = join(parentOf(fileURLToPath(import.meta.url)), "..", "mcp.mjs");
+import { pluginDir, stateAgeSeconds, statePath } from "./pointer.mjs";
+import { readLedger } from "./asks.mjs";
+
+/**
+ * A compaction that had to be repeated within minutes is not solving the problem —
+ * something in the loop is refilling the window as fast as it is emptied, and
+ * another compaction just burns tokens on summarizing. Claude Code detects the same
+ * pathology and calls it thrashing.
+ */
+export const THRASH_WINDOW_MS = 15 * 60_000;
+
+/** The governor's queue, read directly: a hook must not open a daemon connection. */
+export function compactions() {
+  try {
+    const parsed = JSON.parse(readFileSync(join(pluginDir(), "compactions.json"), "utf8"));
+    return Array.isArray(parsed?.items) ? parsed.items : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Already asked and waiting to be delivered: there is nothing to add. */
+export function alreadyQueued(items, agentId) {
+  return items.some(
+    (item) => item.agentId === agentId && (item.state === "pending" || item.state === "sending"),
+  );
+}
+
+export function thrashing(items, agentId, now = Date.now()) {
+  return items.some(
+    (item) =>
+      item.agentId === agentId &&
+      item.state === "sent" &&
+      item.settledAt !== null &&
+      now - Date.parse(item.settledAt) < THRASH_WINDOW_MS,
+  );
+}
+
+function headline({ used, max, pct }) {
+  return `this session holds ${used.toLocaleString()} tokens (${pct}% of a ${max.toLocaleString()}-token window)`;
+}
+
+function why(max) {
+  return max >= 400_000
+    ? "That is worth compacting now even though the window is nowhere near full — what costs you is the prefix re-read on every turn, not the ceiling."
+    : "This is the point where recall degrades noticeably and every turn re-reads an expensive prefix.";
+}
+
+/** The checkpoint half of either ask, which depends on how old the state file is. */
+function checkpointStep(path, age, freshMinutes, then) {
+  if (age === null) {
+    return `There is no task state on disk yet. Call checkpoint — goal, the step in progress and its exact next action, decisions and why, and every approach already tried and rejected — then ${then} Anything you do not write down is gone after the compaction.`;
+  }
+  if (age > freshMinutes * 60) {
+    return `Your task state at ${path} was last written ${Math.round(age / 60)} minutes ago, so it may predate recent work. Call checkpoint to bring it up to date, then ${then}`;
+  }
+  return null;
+}
+
+/**
+ * The end-of-turn question, at the lower line.
+ *
+ * On a large window the headline is the token count, not the percentage: "30% full"
+ * sounds like there is plenty of room, and 300,000 tokens does not.
+ *
+ * It has to be answerable in one turn, so it names the tools and says what to do
+ * with each, and it has to be refusable, or it is not a question — hence the
+ * deferral, which the agent is told about in the same breath.
+ */
+export function askAtTurnEnd(reading, path, age, freshMinutes) {
+  const lines = [
+    `Smart Compact: ${headline(reading)}.`,
+    why(reading.max),
+    "Compacting is your call, not this plugin's, and nothing will happen unless you ask. Do one of these before you stop:",
+  ];
+  const stale = checkpointStep(path, age, freshMinutes, "call request_compaction.");
+  lines.push(
+    stale !== null
+      ? `1. ${stale}`
+      : `1. Your task state at ${path} is current, so this is cheap: call request_compaction with a one-line reason. If work remains, ask it to continue (and optionally choose the follow-up message); if the task is finished, ask it not to continue.`,
+  );
+  lines.push(
+    "2. Or, if this is the wrong moment — mid-refactor, a tool sequence half finished, an answer the user is waiting on — call defer_compaction with a reason and you will not be asked again for a while.",
+    "Either way, do it now and then stop. A queued compaction is delivered as a real /compact once this session goes idle; a follow-up turn is sent only if you requested one.",
+  );
+  return forTools(lines.join("\n"), BRIDGE);
+}
+
+/**
+ * The mid-turn question, at the upper line.
+ *
+ * It arrives after a tool call, in the middle of the agent's work, so it says what
+ * to finish (only the step already under way) and what not to start. The compaction
+ * still lands only once the session is idle, which is why it ends with "then end
+ * your turn": without that the agent would queue it and carry on for an hour.
+ */
+export function askRightAway(reading, upper, path, age, freshMinutes) {
+  const lines = [
+    `Smart Compact: ${headline(reading)}, past its upper line of ${upper}%.`,
+    `This is the line where you should not push on. ${why(reading.max)}`,
+    "Finish only the atomic step you are on — the edit half applied, the command already running — and do not start a new step, read a large file or begin another tool sequence. Then:",
+  ];
+  const stale = checkpointStep(path, age, freshMinutes, "go on to step 2.");
+  lines.push(stale !== null ? `1. ${stale}` : `1. Your task state at ${path} is current, so go straight to step 2.`);
+  lines.push(
+    "2. Call request_compaction with continue_after_compaction set to true and a one-line reason. If you know the next action, put it in continue_message so the follow-up names it.",
+    "3. End your turn. The compaction is delivered as a real /compact once this session goes idle, so it cannot land while you keep working.",
+    "If stopping now would leave something broken that the next turn could not pick up, call defer_compaction with that reason instead — you will be asked again when it runs out. Do not defer just to keep going.",
+  );
+  return forTools(lines.join("\n"), BRIDGE);
+}
+
+/**
+ * What to say instead, when compacting is not the answer.
+ *
+ * Said once, as an ask, so it counts against the same latch: repeating it every
+ * turn would be the nagging these hooks exist to avoid.
+ */
+export function thrashAdvice({ used, pct }) {
+  return forTools([
+    `Smart Compact: this session refilled to ${used.toLocaleString()} tokens (${pct}%) within minutes of its last compaction.`,
+    "Compacting again would not help — something in this loop is reading far more than it keeps, so the window would refill just as fast and you would pay for another summary.",
+    "Write what you have learned to your state file with checkpoint, then either change the approach so it stops re-reading the same material, or finish and let a fresh session take the rest.",
+  ].join("\n"), BRIDGE);
+}
+
+/**
+ * Whether there is anyone to ask, and how full they are.
+ *
+ * The guards both hooks share: a subagent is never asked (its window is its own),
+ * Smart Compact must be on, the session must be enrolled, and the transcript must
+ * have a reading. Returns null whenever the answer is "say nothing".
+ */
+export function askable(event) {
+  if (event.agent_id !== undefined && event.agent_id !== null) return null;
+  const transcriptPath = event.transcript_path;
+  const sessionId = event.session_id;
+  if (typeof transcriptPath !== "string" || typeof sessionId !== "string") return null;
+
+  const settings = readSettings();
+  if (!settings.enabled) return null;
+
+  const agentId = process.env.PASEO_AGENT_ID ?? null;
+  if (!isEnrolled(agentId, settings)) return null;
+
+  const reading = occupancy(transcriptPath, settings);
+  if (reading === null) return null;
+  return { sessionId, agentId, settings, reading };
+}
+
+/**
+ * The text to put to the agent at one of the two lines, or null for silence.
+ *
+ * `line` is "compact" (end of turn) or "now" (right away). `allowed` is that
+ * line's own back-off rule over the ledger. The queue is read last because it is
+ * the most expensive check and the others usually decide first.
+ */
+export function compose(context, line, allowed) {
+  const { sessionId, agentId, settings, reading } = context;
+  if (reading.pct < reading.profile[line]) return null;
+
+  const ledger = readLedger(sessionId);
+  if (!allowed(ledger, reading.pct)) return null;
+
+  const queue = compactions();
+  if (alreadyQueued(queue, agentId)) return null;
+
+  const path = statePath();
+  const age = stateAgeSeconds(path);
+  let text;
+  if (thrashing(queue, agentId)) text = thrashAdvice(reading);
+  else if (line === "now") text = askRightAway(reading, reading.profile.now, path, age, settings.freshStateMinutes);
+  else text = askAtTurnEnd(reading, path, age, settings.freshStateMinutes);
+  return { text, ledger };
+}

package/hooks/asks.mjs

@@ -1,117 +1,2 @@
-/**
- * The record of what this session has already been asked, and what it answered.
- *
- * Asking once and never again lets a session drift; asking every turn is nagging.
- * So the ask is latched, re-armed by growth rather than by a clock alone, and can
- * be switched off for a while by the agent itself — that last part is what makes it
- * a question instead of an announcement.
- *
- * One file per agent rather than one shared file. `state/<agentId>.md` already
- * works that way, and it means the `Stop` hook and the `defer_compaction` tool —
- * two separate processes — can never be writing the same file at the same moment.
- */
-
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { join } from "node:path";
-
-import { pluginDir } from "./pointer.mjs";
-
-/** Asks per compaction epoch, after which the session is left to its own judgement. */
-export const MAX_ASKS = 3;
-
-/**
- * Further occupancy, in percentage points of the window, that re-arms the ask.
- *
- * Time alone is the wrong trigger: a session parked at 31% for an hour has not
- * changed its situation, and one that went 31% to 55% in ten minutes plainly has.
- */
-export const RE_ASK_GROWTH_PCT = 10;
-
-const EMPTY = { askCount: 0, lastAskedAt: null, askedAtPct: null, deferredUntil: null, deferReason: null };
-
-/**
- * Keyed by Paseo agent id where there is one, because that survives compaction
- * whatever Claude Code decides to do with the session id.
- */
-export function ledgerPath(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(), "asks", `${key.replace(/[^A-Za-z0-9_-]/g, "_")}.json`);
-}
-
-export function readLedger(sessionId) {
-  const path = ledgerPath(sessionId);
-  if (path === null) return { ...EMPTY };
-  try {
-    return { ...EMPTY, ...JSON.parse(readFileSync(path, "utf8")) };
-  } catch {
-    return { ...EMPTY };
-  }
-}
-
-export function writeLedger(sessionId, ledger) {
-  const path = ledgerPath(sessionId);
-  if (path === null) return;
-  try {
-    mkdirSync(join(pluginDir(), "asks"), { recursive: true });
-    const temp = `${path}.${randomUUID()}.tmp`;
-    writeFileSync(temp, JSON.stringify(ledger), "utf8");
-    renameSync(temp, path);
-  } catch {
-    // A hook that cannot persist its latch must still not break the turn.
-  }
-}
-
-/**
- * Forgets everything, because the window just emptied.
- *
- * A compaction is a new epoch: the occupancy the last ask was about is gone, and a
- * session that fills up again deserves to be asked again.
- */
-export function resetLedger(sessionId) {
-  const path = ledgerPath(sessionId);
-  if (path === null) return;
-  try {
-    rmSync(path, { force: true });
-  } catch {
-    // A stale ledger costs one missed ask, never a failed turn.
-  }
-}
-
-/** The agent's own answer: not now, and here is for how long. */
-export function defer(sessionId, minutes, reason) {
-  const ledger = readLedger(sessionId);
-  const until = new Date(Date.now() + minutes * 60_000).toISOString();
-  writeLedger(sessionId, { ...ledger, deferredUntil: until, deferReason: reason });
-  return until;
-}
-
-/**
- * Whether to ask, given what has already been said and how much has changed.
- *
- * `pct` is the occupancy now; `askedAtPct` the occupancy the last ask was about.
- */
-export function shouldAsk(ledger, pct, now = Date.now()) {
-  if (ledger.deferredUntil !== null) {
-    const until = Date.parse(ledger.deferredUntil);
-    if (Number.isFinite(until) && now < until) return false;
-  }
-  if (ledger.askCount >= MAX_ASKS) return false;
-  if (ledger.askedAtPct === null) return true;
-  return pct >= ledger.askedAtPct + RE_ASK_GROWTH_PCT;
-}
-
-/** Records that the question was actually put to the model. */
-export function recordAsk(sessionId, ledger, pct) {
-  writeLedger(sessionId, {
-    ...ledger,
-    askCount: ledger.askCount + 1,
-    lastAskedAt: new Date().toISOString(),
-    askedAtPct: pct,
-    // An answered ask clears the deferral it was waiting out.
-    deferredUntil: null,
-    deferReason: null,
-  });
-}
+// Moved to server/hooklib so the server bundle (native agent tools) can share it; hooks keep importing it from here.
+export * from "../server/hooklib/asks.mjs";

package/hooks/context-threshold.mjs

@@ -8,8 +8,11 @@
  * short line the moment context crosses each band. Each level fires once per
  * compaction epoch, so a long session gets three sentences, not three hundred.
  *
- * It describes; it never asks for anything. Deciding that a session should compact
- * belongs at a turn boundary, and that is `ask-compact.mjs` on `Stop`.
+ * Below Smart Compact's upper line it only describes; the end-of-turn question at
+ * the lower line is `ask-compact.mjs` on `Stop`. Past the upper line it asks right
+ * away, because that is the line where the agent should not start anything new —
+ * once per compaction epoch, again only after a deferral runs out, and through the
+ * same guards as the `Stop` hook (`ask.mjs`).
  *
  * It reads the transcript rather than asking Paseo, so it works in any Claude Code
  * session, and it reads only the tail of it, because this runs on the hot path.
@@ -18,7 +21,10 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-import { BANDS, DEFAULT_THRESHOLDS, occupancy, readSettings } from "./context.mjs";
+import { askable, compose } from "./ask.mjs";
+import { recordNowAsk, shouldAskNow } from "./asks.mjs";
+import { BANDS, DEFAULT_THRESHOLDS, detachedNotice, occupancy, readSettings, toolsMode } from "./context.mjs";
+import { BRIDGE } from "./ask.mjs";
 import { clearPending, pluginDir, readPending, statePath } from "./pointer.mjs";
 
 function latchPathFor(sessionId) {
@@ -102,6 +108,8 @@ async function main() {
   const parts = [];
   const pending = readPending(sessionId);
   if (pending !== null) parts.push(pending);
+  // A smart_* call that just failed because a plugin update detached the tools: say how to reach them meanwhile.
+  if (/^mcp__paseo__smart_/.test(String(event.tool_name ?? "")) && toolsMode() === "detached") parts.push(detachedNotice(BRIDGE));
 
   const now = occupancy(transcriptPath, readSettings());
   if (now === null) return emit(sessionId, parts, pending);
@@ -117,20 +125,36 @@ async function main() {
 
   const reached = BANDS.filter((band) => now.pct >= now.profile[band]);
   const crossed = reached.filter((band) => !latch.fired.includes(band));
-  if (crossed.length === 0) {
-    writeLatch(latchPath, latch);
-    return emit(sessionId, parts, pending);
-  }
-
-  // A session that jumped two bands in one turn hears the more urgent one.
-  const band = crossed[crossed.length - 1];
   latch.fired = [...new Set([...latch.fired, ...crossed])];
   writeLatch(latchPath, latch);
 
-  parts.push(advice(band, now.pct, now.used, now.max, statePath()));
+  // Past the upper line, the question replaces the description: it says everything
+  // the band line would, and two messages about the same moment read as two.
+  const asked = now.pct >= now.profile.now ? askNow(event) : null;
+  if (asked !== null) {
+    parts.push(asked.text);
+    emit(sessionId, parts, pending);
+    // Recorded only once it has reached stdout, like the `Stop` hook's ask.
+    recordNowAsk(sessionId, asked.ledger);
+    return;
+  }
+
+  // A session that jumped two bands in one turn hears the more urgent one.
+  if (crossed.length > 0) parts.push(advice(crossed[crossed.length - 1], now.pct, now.used, now.max, statePath()));
   return emit(sessionId, parts, pending);
 }
 
+/** The upper line's question, or null when one of the shared guards says no. */
+function askNow(event) {
+  try {
+    const context = askable(event);
+    if (context === null) return null;
+    return compose(context, "now", (ledger) => shouldAskNow(ledger));
+  } catch {
+    return null; // The ask is never worth failing the tool call it rides on.
+  }
+}
+
 /**
  * Writes whatever there is to say, and only then forgets the pending pointer:
  * clearing it before it reaches stdout would lose it on any later failure.

package/hooks/context.mjs

@@ -1,233 +1,2 @@
-/**
- * What every hook needs to know about the session it is running in.
- *
- * Two hooks now answer "how full is this context" — `context-threshold.mjs` on
- * `PostToolUse` and `ask-compact.mjs` on `Stop` — and they must not disagree. One
- * reading them differently from the other would mean the agent hears the number and
- * the advice from two different sessions.
- *
- * Everything here reads the tail of a file rather than the whole of it: these run
- * on the hot path, and the newest row is the only one that matters.
- */
-
-import { closeSync, fstatSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
-import { join } from "node:path";
-
-import { pluginDir } from "./pointer.mjs";
-
-/** Enough tail to contain the last assistant message in any realistic transcript. */
-const TAIL_BYTES = 256 * 1024;
-
-/**
- * Defaults mirroring thresholds.shared.ts, used when the plugin has not written a
- * settings file yet. Kept in sync by a test that runs the hooks and checks where
- * they fire against the shared module's numbers.
- *
- * Two profiles because a percentage of the window is the wrong unit on its own:
- * what tires a context is the absolute prefix re-read every turn, so 30% of a
- * million tokens is a heavier context than 85% of two hundred thousand.
- */
-export const DEFAULT_THRESHOLDS = {
-  largeWindowFrom: 400_000,
-  large: { notice: 15, closing: 22, compact: 30 },
-  small: { notice: 60, closing: 75, compact: 85 },
-};
-
-export const BANDS = ["notice", "closing", "compact"];
-
-export const DEFAULT_SETTINGS = {
-  enabled: true,
-  showPill: true,
-  autoEnrol: true,
-  freshStateMinutes: 30,
-  thresholds: DEFAULT_THRESHOLDS,
-};
-
-/** The plugin's settings are the single source of truth when they exist. */
-export function readSettings() {
-  try {
-    const raw = JSON.parse(readFileSync(join(pluginDir(), "settings.json"), "utf8"));
-    const merged = { ...DEFAULT_THRESHOLDS, ...(raw.thresholds ?? {}) };
-    return {
-      // Absent means an install that predates the switch, which was always meant
-      // to be on once it could only ask rather than act.
-      enabled: raw.enabled !== false,
-      showPill: raw.showPill !== false,
-      autoEnrol: raw.autoEnrol !== false,
-      freshStateMinutes:
-        typeof raw.freshStateMinutes === "number" && raw.freshStateMinutes > 0
-          ? raw.freshStateMinutes
-          : DEFAULT_SETTINGS.freshStateMinutes,
-      thresholds: {
-        largeWindowFrom: merged.largeWindowFrom ?? DEFAULT_THRESHOLDS.largeWindowFrom,
-        large: { ...DEFAULT_THRESHOLDS.large, ...(merged.large ?? {}) },
-        small: { ...DEFAULT_THRESHOLDS.small, ...(merged.small ?? {}) },
-      },
-    };
-  } catch {
-    return DEFAULT_SETTINGS;
-  }
-}
-
-export function profileFor(maxTokens, thresholds) {
-  return maxTokens >= thresholds.largeWindowFrom ? thresholds.large : thresholds.small;
-}
-
-/**
- * Whether this agent is one the governor may speak to.
- *
- * The same rule settings.server.ts resolves, duplicated here because a hook on the
- * hot path must not open a daemon connection to answer it: an explicit answer in
- * `enrolment.json` outranks the state-file inference in both directions, and the
- * inference itself only counts while `autoEnrol` is on.
- */
-export function isEnrolled(agentId, settings = readSettings()) {
-  if (typeof agentId !== "string" || agentId === "") return false;
-  try {
-    const overrides = JSON.parse(readFileSync(join(pluginDir(), "enrolment.json"), "utf8"));
-    if (typeof overrides?.[agentId] === "boolean") return overrides[agentId];
-  } catch {
-    // No file, or one we cannot read: nobody has overridden anything.
-  }
-  if (!settings.autoEnrol) return false;
-  try {
-    return readdirSync(join(pluginDir(), "state")).includes(`${agentId}.md`);
-  } catch {
-    return false;
-  }
-}
-
-/** The tail of a file as text, or null if it cannot be read. */
-function tail(path, bytes) {
-  let fd;
-  try {
-    fd = openSync(path, "r");
-  } catch {
-    return null;
-  }
-  try {
-    const size = fstatSync(fd).size;
-    const length = Math.min(size, bytes);
-    const buffer = Buffer.allocUnsafe(length);
-    readSync(fd, buffer, 0, length, size - length);
-    return buffer.toString("utf8");
-  } catch {
-    return null;
-  } finally {
-    closeSync(fd);
-  }
-}
-
-/**
- * Context occupancy from the last assistant message's usage.
- *
- * input + cache_read + cache_creation + output is the same arithmetic Claude Code
- * itself documents for a resumed session's `context_tokens`, so it is the
- * sanctioned way to ask "how much of the window is currently occupied".
- */
-export function readContextTokens(transcriptPath) {
-  const text = tail(transcriptPath, TAIL_BYTES);
-  if (text === null) return null;
-  const lines = text.split("\n");
-
-  // Backwards: the newest assistant message wins, and a partial first line from
-  // slicing mid-file simply fails to parse and is skipped.
-  for (let index = lines.length - 1; index >= 0; index -= 1) {
-    const line = lines[index];
-    if (line === undefined || line === "" || !line.includes('"usage"')) continue;
-    let entry;
-    try {
-      entry = JSON.parse(line);
-    } catch {
-      continue;
-    }
-    if (entry?.type !== "assistant") continue;
-    // A subagent's usage is its own window, not the main thread's.
-    if (entry.isSidechain === true) continue;
-    const usage = entry.message?.usage;
-    if (usage === undefined) continue;
-    const used =
-      (usage.input_tokens ?? 0) +
-      (usage.cache_read_input_tokens ?? 0) +
-      (usage.cache_creation_input_tokens ?? 0) +
-      (usage.output_tokens ?? 0);
-    return { used, model: entry.message?.model ?? null };
-  }
-  return null;
-}
-
-/**
- * Models whose context window is not the current default of 1M.
- *
- * The transcript records the resolved model id (`claude-opus-5`), never the config
- * alias (`opus[1m]`), so the suffix is not a signal. Every current Opus, Sonnet and
- * Fable model has a 1M window; Haiku and the older generations do not.
- */
-const SMALL_WINDOW = /haiku|-3-|sonnet-3|opus-3|sonnet-4-5|opus-4-5|sonnet-4-20|opus-4-20/;
-
-/**
- * The window size Paseo reported for this agent, from the recorder's own log.
- *
- * Read from the tail, like the transcript: this is the hot path, and the newest row
- * is the only one that matters.
- */
-function recordedWindow() {
-  const agentId = process.env.PASEO_AGENT_ID;
-  if (agentId === undefined || agentId === "") return null;
-  const month = new Date().toISOString().slice(0, 7);
-  const text = tail(join(pluginDir(), `context-${month}.jsonl`), 64 * 1024);
-  if (text === null) return null;
-
-  const lines = text.split("\n");
-  for (let index = lines.length - 1; index >= 0; index -= 1) {
-    const line = lines[index];
-    if (line === undefined || !line.includes(agentId)) continue;
-    try {
-      const row = JSON.parse(line);
-      if (row.agentId === agentId && typeof row.maxTokens === "number" && row.maxTokens > 0) {
-        return row.maxTokens;
-      }
-    } catch {
-      continue;
-    }
-  }
-  return null;
-}
-
-/**
- * The window size for this session.
- *
- * Getting this wrong is worse than not warning at all: assuming 200k on a 1M
- * session warns at a fifth of the real occupancy and reports negative headroom.
- * So the first choice is what Paseo actually measured for this agent — recorded by
- * the plugin, read from the tail of its log — and the model table is the fallback.
- */
-export function windowFor(model) {
-  const override = Number(process.env.SMART_SESSION_CONTEXT_WINDOW ?? "");
-  if (Number.isFinite(override) && override > 0) return override;
-
-  const recorded = recordedWindow();
-  if (recorded !== null) return recorded;
-
-  if (typeof model === "string" && SMALL_WINDOW.test(model)) return 200_000;
-  return 1_000_000;
-}
-
-/**
- * Occupancy, the window it is measured against, and the bands that apply.
- *
- * Returns null when the transcript says nothing yet — a session with no completed
- * assistant turn has no usage to read, and guessing would be worse than silence.
- */
-export function occupancy(transcriptPath, settings = readSettings()) {
-  const reading = readContextTokens(transcriptPath);
-  if (reading === null) return null;
-  const max = windowFor(reading.model);
-  return {
-    used: reading.used,
-    max,
-    model: reading.model,
-    pct: Math.floor((reading.used / max) * 100),
-    profile: profileFor(max, settings.thresholds),
-  };
-}
+// Moved to server/hooklib so the server bundle (native agent tools) can share it; hooks keep importing it from here.
+export * from "../server/hooklib/context.mjs";