paseo-smart-session 3.5.0 → 3.6.0

package/README.md

@@ -20,7 +20,7 @@ Screenshots use synthetic usage history and sessions.
 paseo plugin install paseo-smart-session
 ```
 
-On first load it registers its Claude Code hooks, touching only entries that point at its own scripts. Paseo attaches its MCP server when an interactive session opens.
+On first load it registers its Claude Code hooks, touching only entries that point at its own scripts. Its agent tools are attached when an interactive session opens: on Paseo 0.15+ they are served through the agent's own Paseo MCP (`smart_checkpoint`, `smart_request_compaction`, …) with no process per agent, and on 0.14 each session gets its own `mcp.mjs` stdio server. Nothing is registered globally; an older version's global `smart-session` entry is removed on load, with a backup beside the file.
 
 ## Use
 

package/hooks/ask.mjs

@@ -15,7 +15,12 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { isEnrolled, occupancy, readSettings } from "./context.mjs";
+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";
 
@@ -101,7 +106,7 @@ export function askAtTurnEnd(reading, path, age, freshMinutes) {
     "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 lines.join("\n");
+  return forTools(lines.join("\n"), BRIDGE);
 }
 
 /**
@@ -125,7 +130,7 @@ export function askRightAway(reading, upper, path, age, freshMinutes) {
     "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 lines.join("\n");
+  return forTools(lines.join("\n"), BRIDGE);
 }
 
 /**
@@ -135,11 +140,11 @@ export function askRightAway(reading, upper, path, age, freshMinutes) {
  * turn would be the nagging these hooks exist to avoid.
  */
 export function thrashAdvice({ used, pct }) {
-  return [
+  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");
+  ].join("\n"), BRIDGE);
 }
 
 /**

package/hooks/asks.mjs

@@ -1,164 +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;
-
-/**
- * `now*` is the upper line's own record. It is kept apart from the end-of-turn ask
- * so that having been asked politely at the lower line never silences the one ask
- * that says "stop pushing on", and `deferredAt` survives an answered ask so the
- * upper line can tell "deferred after I asked" from "never answered".
- */
-const EMPTY = {
-  askCount: 0,
-  lastAskedAt: null,
-  askedAtPct: null,
-  deferredUntil: null,
-  deferReason: null,
-  deferredAt: null,
-  nowAskCount: 0,
-  nowAskedAt: 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, deferredAt: new Date().toISOString() });
-  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.
- */
-function deferred(ledger, now) {
-  if (ledger.deferredUntil === null) return false;
-  const until = Date.parse(ledger.deferredUntil);
-  return Number.isFinite(until) && now < until;
-}
-
-export function shouldAsk(ledger, pct, now = Date.now()) {
-  if (deferred(ledger, now)) 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,
-  });
-}
-
-/**
- * Whether to ask right away, mid-turn, at the upper line.
- *
- * Once per compaction epoch. It comes back only if the agent answered the last one
- * with a deferral and that deferral has run out — ignoring it earns no repeat, so a
- * long turn hears it once rather than after every tool call — and never more than
- * `MAX_ASKS` times in all. Any live deferral, from either ask, holds it off: the
- * agent's "not now" is one answer, not one per line.
- */
-export function shouldAskNow(ledger, now = Date.now()) {
-  if (deferred(ledger, now)) return false;
-  if (ledger.nowAskCount === 0 || ledger.nowAskedAt === null) return true;
-  if (ledger.nowAskCount >= MAX_ASKS) return false;
-  const asked = Date.parse(ledger.nowAskedAt);
-  const answered = ledger.deferredAt === null ? Number.NaN : Date.parse(ledger.deferredAt);
-  return Number.isFinite(asked) && Number.isFinite(answered) && answered >= asked;
-}
-
-/** Records that the upper line's question was put to the model. */
-export function recordNowAsk(sessionId, ledger) {
-  writeLedger(sessionId, {
-    ...ledger,
-    nowAskCount: ledger.nowAskCount + 1,
-    nowAskedAt: new Date().toISOString(),
-    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

@@ -23,7 +23,8 @@ import { dirname, join } from "node:path";
 
 import { askable, compose } from "./ask.mjs";
 import { recordNowAsk, shouldAskNow } from "./asks.mjs";
-import { BANDS, DEFAULT_THRESHOLDS, occupancy, readSettings } from "./context.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) {
@@ -107,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);

package/hooks/context.mjs

@@ -1,247 +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, now: 40 },
-  small: { notice: 60, closing: 75, compact: 85, now: 90 },
-};
-
-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: withUpperLine(merged.large, DEFAULT_THRESHOLDS.large),
-        small: withUpperLine(merged.small, DEFAULT_THRESHOLDS.small),
-      },
-    };
-  } catch {
-    return DEFAULT_SETTINGS;
-  }
-}
-
-/**
- * A saved profile, with the upper line filled in when it predates one.
- *
- * Mirrors `normalizeProfile` in thresholds.ts: the saved lower line is kept, and an
- * absent upper line keeps the default's distance above it, never falling below it.
- */
-export function withUpperLine(saved, fallback) {
-  const profile = { ...fallback, ...(saved ?? {}) };
-  const compact = profile.compact;
-  const migrated = Math.min(99, Math.max(fallback.now, compact + (fallback.now - fallback.compact)));
-  const raw = typeof saved?.now === "number" && Number.isFinite(saved.now) ? saved.now : migrated;
-  return { ...profile, now: Math.min(99, Math.max(Math.min(99, compact + 1), raw)) };
-}
-
-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";

package/hooks/pointer.mjs

@@ -1,149 +1,2 @@
-/**
- * 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.
-  }
-}
+// Moved to server/hooklib so the server bundle (native agent tools) can share it; hooks keep importing it from here.
+export * from "../server/hooklib/pointer.mjs";