switchroom 0.12.16 → 0.12.17

package/telegram-plugin/gateway/gateway.ts

@@ -228,6 +228,8 @@ import { handleInjectCommand } from './inject-handler.js'
 import { type BannerState } from '../slot-banner.js'
 import { refreshBanner } from '../slot-banner-driver.js'
 import { loadConfig as loadSwitchroomConfig } from '../../src/config/loader.js'; import { resolveAgentConfig } from '../../src/config/merge.js'
+import { readTurnUsages } from '../../src/agents/perf.js'
+import { decideProactiveCompact, initialCompactState, type CompactState } from './proactive-compact.js'
 import {
   tryHostdDispatch,
   hostdRequestId,
@@ -1062,6 +1064,28 @@ const chatAvailableReactions = new Map<string, Set<string> | null>()
 const chatProbesInFlight = new Set<string>()
 const activeTurnStartedAt = new Map<string, number>()
 const pendingRestarts = new Map<string, number>()  // agentName -> timestamp when restart was requested
+
+// ─── Proactive context compaction (session.max_context_tokens) ──────────
+//
+// Opt-in: when the resolved agent config sets session.max_context_tokens,
+// we fire `/compact` once the live context-window occupancy of the latest
+// assistant turn reaches that many tokens. Evaluated ONLY at the
+// model-idle gate inside purgeReactionTracking (activeTurnStartedAt.size
+// === 0) — never mid-turn — mirroring the pendingRestarts drain. The
+// `/compact` verb is allowlisted in src/agents/inject.ts and runs via the
+// tmux send-keys path (the only path that actually executes the slash
+// command; inject_inbound would deliver it as literal text).
+//
+// `lastSessionActiveFile` is the session-tail's tracked currentFile,
+// forwarded by the bridge on every session_event — we read occupancy from
+// exactly that file (never an independent findActiveSessionFile re-scan).
+let lastSessionActiveFile: string | null = null
+// Anti-spam state machine lives in ./proactive-compact (pure, unit
+// tested). `compactDispatching` is a synchronous re-entrancy guard for
+// the async tmux send — purgeReactionTracking can run several times per
+// turn and we must not double-dispatch before the first send settles.
+let compactState: CompactState = initialCompactState()
+let compactDispatching = false
 const activeDraftStreams = new Map<string, DraftStreamHandle>()
 const activeDraftParseModes = new Map<string, 'HTML' | 'MarkdownV2' | undefined>()
 const suppressPtyPreview = new Set<string>()
@@ -1233,14 +1257,94 @@ function purgeReactionTracking(key: string): void {
   // survives us getting killed by our own restart. Fire-and-forget;
   // response to the client was already sent when the restart was
   // scheduled, so nobody is waiting on this.
-  if (activeTurnStartedAt.size === 0 && pendingRestarts.size > 0) {
-    for (const [agentName, _timestamp] of pendingRestarts.entries()) {
-      triggerSelfRestart(agentName, 'turn-complete-pending-restart');
-      pendingRestarts.delete(agentName);
+  if (activeTurnStartedAt.size === 0) {
+    if (pendingRestarts.size > 0) {
+      for (const [agentName, _timestamp] of pendingRestarts.entries()) {
+        triggerSelfRestart(agentName, 'turn-complete-pending-restart');
+        pendingRestarts.delete(agentName);
+      }
+    } else {
+      // Strictly lower priority than a pending restart: if we just
+      // kicked a restart the process is going away and compacting is
+      // moot, so only evaluate when no restart drained this pass.
+      maybeProactiveCompact();
     }
   }
 }
 
+/**
+ * Model-idle proactive-compaction check. Called ONLY from the
+ * activeTurnStartedAt.size === 0 gate above (never mid-turn). Opt-in via
+ * the resolved agent config's session.max_context_tokens; a no-op when
+ * unset, so a fresh `switchroom setup` is unchanged.
+ *
+ * Occupancy = the latest usage-bearing assistant turn's
+ * input + cache_read + cache_creation tokens (the prefix the model
+ * actually re-read this turn ≈ current window fill). readTurnUsages(_,1)
+ * returns exactly that single turn and skips tool-only / usage-less
+ * lines, so we never under-count off a sub-line.
+ *
+ * Note (accepted, benign): there is a check-to-send race — a new inbound
+ * could set activeTurnStartedAt between this idle check and the async
+ * tmux send. A `/compact` that lands as a new turn starts is queued in
+ * claude's prompt buffer and runs at the next idle prompt (see the
+ * FUTURE-GAP note in src/agents/inject.ts); it is not a mid-generation
+ * injection. We do not claim size===0 is atomic.
+ */
+function maybeProactiveCompact(): void {
+  if (compactDispatching) return;
+
+  const agentName = process.env.SWITCHROOM_AGENT_NAME;
+  if (!agentName) return;
+
+  let cap: number | undefined;
+  try {
+    const cfg = loadSwitchroomConfig();
+    // Resolve through the cascade so a fleet-wide
+    // `defaults.session.max_context_tokens` applies even when the agent
+    // has no explicit per-agent session block (rawAgent → {}).
+    const rawAgent = cfg.agents?.[agentName] ?? {};
+    const resolved = resolveAgentConfig(cfg.defaults, cfg.profiles, rawAgent);
+    cap = resolved.session?.max_context_tokens;
+  } catch {
+    // Best-effort — config may be unreadable in odd boot states; a
+    // failed read just means "no proactive compaction this pass".
+    return;
+  }
+  if (cap == null || cap <= 0) return; // opt-in: unset → native compaction only
+
+  const file = lastSessionActiveFile;
+  if (!file) return;
+
+  const turns = readTurnUsages(file, 1);
+  if (turns.length === 0) return;
+  const t = turns[0];
+  const occupancy = t.input + t.cacheRead + t.cacheCreate;
+
+  const decision = decideProactiveCompact(compactState, occupancy, cap);
+  compactState = decision.state;
+  if (!decision.fire) return;
+
+  // Set the re-entrancy guard synchronously BEFORE the await so a
+  // re-entrant purge pass can't double-dispatch (the decider already
+  // disarmed + armed the cooldown in decision.state).
+  compactDispatching = true;
+  process.stderr.write(
+    `telegram gateway: proactive /compact for ${agentName} ` +
+      `(occupancy=${occupancy} >= cap=${cap})\n`,
+  );
+  void injectSlashCommandImpl(agentName, '/compact')
+    .catch((err: unknown) => {
+      process.stderr.write(
+        `telegram gateway: proactive /compact inject failed for ` +
+          `${agentName}: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+    })
+    .finally(() => {
+      compactDispatching = false;
+    });
+}
+
 function endStatusReaction(chatId: string, threadId: number | undefined, outcome: 'done' | 'error'): void {
   const key = statusKey(chatId, threadId)
   const ctrl = activeStatusReactions.get(key)
@@ -2997,6 +3101,9 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onSessionEvent(_client: IpcClient, msg: SessionEventForward) {
+    // Track the session-tail's attached file for the proactive-
+    // compaction occupancy read (see maybeProactiveCompact).
+    if (msg.activeFile) lastSessionActiveFile = msg.activeFile
     const ev = msg.event as unknown as SessionEvent
     // Pass the envelope's chatId so non-enqueue events can route to the
     // correct card even when the driver's currentChatId is stale.

package/telegram-plugin/gateway/ipc-protocol.ts

@@ -121,6 +121,15 @@ export interface SessionEventForward {
   event: Record<string, unknown>;
   chatId: string;
   threadId?: number;
+  /**
+   * The session-tail's currently-attached JSONL path (its tracked
+   * `currentFile`, not an independent re-scan). Forwarded so the
+   * gateway's proactive-compaction check reads occupancy from the
+   * exact file the tailer is on — avoids the sub-agent-mtime /
+   * stale-rotation wrong-file hazard. Absent until the tailer has
+   * attached a file.
+   */
+  activeFile?: string;
 }
 
 export interface PermissionRequestForward {

package/telegram-plugin/gateway/proactive-compact.ts

@@ -0,0 +1,84 @@
+/**
+ * Pure decision core for proactive context compaction
+ * (`session.max_context_tokens`). Kept side-effect-free so the
+ * anti-spam state machine — the part most prone to livelock /
+ * double-fire — is unit-testable in isolation. The impure shell
+ * (config load, session-file read, tmux `/compact` inject) lives in
+ * gateway.ts and calls `decideProactiveCompact` at the model-idle gate.
+ *
+ * Occupancy fed in by the caller = the latest usage-bearing assistant
+ * turn's `input + cache_read + cache_creation` tokens (the prefix the
+ * model re-read this turn ≈ live context-window fill). Not cumulative.
+ */
+
+/** Hysteresis lower band: re-arm only once occupancy < fraction × cap. */
+export const COMPACT_REARM_FRACTION = 0.6;
+
+/**
+ * Turn-count re-fire floor: after a fire, skip this many idle
+ * evaluations regardless of occupancy. Guards against a slow
+ * post-`/compact` JSONL rotation still reading the pre-compact turn and
+ * triggering an immediate second compaction.
+ */
+export const COMPACT_COOLDOWN_TURNS = 3;
+
+export interface CompactState {
+  /** False after a fire; re-armed only below the hysteresis band. */
+  armed: boolean;
+  /** Idle evaluations remaining before re-fire is even considered. */
+  cooldownTurns: number;
+}
+
+export interface CompactDecision {
+  fire: boolean;
+  /** Next state — caller must persist this verbatim. */
+  state: CompactState;
+}
+
+export function initialCompactState(): CompactState {
+  return { armed: true, cooldownTurns: 0 };
+}
+
+/**
+ * Decide whether to fire `/compact` this idle evaluation, given the
+ * current state, the measured occupancy, and the configured cap.
+ *
+ * Precedence (each returns early):
+ *  1. Cooldown floor — burn one turn, never fire.
+ *  2. Disarmed — re-arm iff occupancy < REARM_FRACTION × cap; never
+ *     fire on the arming pass (so we can't arm and fire together).
+ *  3. Below cap — hold.
+ *  4. Armed and at/above cap — fire, disarm, start the cooldown.
+ *
+ * Livelock safety: once disarmed, step 2 is the ONLY path back to
+ * armed, and it requires occupancy to actually drop below the lower
+ * band. If a compaction fails to shrink context, the cap stays
+ * exceeded, occupancy never drops below 0.6×cap, and we stay disarmed
+ * — i.e. we degrade to "don't fire" rather than firing every turn.
+ */
+export function decideProactiveCompact(
+  state: CompactState,
+  occupancy: number,
+  cap: number,
+): CompactDecision {
+  if (state.cooldownTurns > 0) {
+    return {
+      fire: false,
+      state: { armed: state.armed, cooldownTurns: state.cooldownTurns - 1 },
+    };
+  }
+
+  if (!state.armed) {
+    const armed = occupancy < cap * COMPACT_REARM_FRACTION;
+    return { fire: false, state: { armed, cooldownTurns: 0 } };
+  }
+
+  if (occupancy < cap) {
+    return { fire: false, state };
+  }
+
+  return {
+    fire: true,
+    state: { armed: false, cooldownTurns: COMPACT_COOLDOWN_TURNS },
+  };
+}

package/telegram-plugin/tests/proactive-compact.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import {
+  decideProactiveCompact,
+  initialCompactState,
+  COMPACT_COOLDOWN_TURNS,
+  COMPACT_REARM_FRACTION,
+  type CompactState,
+} from '../gateway/proactive-compact.js'
+
+const CAP = 190_000
+
+// Drive the state machine over a sequence of occupancy readings,
+// returning the index of every evaluation that fired.
+function run(occ: number[], start: CompactState = initialCompactState()) {
+  let state = start
+  const fires: number[] = []
+  occ.forEach((o, i) => {
+    const d = decideProactiveCompact(state, o, CAP)
+    state = d.state
+    if (d.fire) fires.push(i)
+  })
+  return { state, fires }
+}
+
+describe('decideProactiveCompact', () => {
+  it('does not fire below the cap', () => {
+    const { fires } = run([0, 50_000, 150_000, CAP - 1])
+    expect(fires).toEqual([])
+  })
+
+  it('fires exactly once when occupancy reaches the cap, then disarms', () => {
+    // Stays high after the fire (compaction has not landed yet).
+    const { fires } = run([CAP, CAP, CAP])
+    expect(fires).toEqual([0])
+  })
+
+  it('fires at occupancy strictly above the cap too', () => {
+    const { fires } = run([CAP + 25_000])
+    expect(fires).toEqual([0])
+  })
+
+  it('burns exactly COMPACT_COOLDOWN_TURNS idle evals after a fire before re-considering', () => {
+    // Fire at 0, then occupancy stays pegged high. The cooldown must
+    // swallow the next COMPACT_COOLDOWN_TURNS evals with no fire, and
+    // because it is still above the re-arm band it never re-arms ->
+    // never fires again. (Livelock guard.)
+    const seq = new Array(1 + COMPACT_COOLDOWN_TURNS + 5).fill(CAP)
+    const { fires } = run(seq)
+    expect(fires).toEqual([0])
+  })
+
+  it('re-arms only after occupancy falls below REARM_FRACTION × cap, never on the arming pass', () => {
+    const lowBand = CAP * COMPACT_REARM_FRACTION
+    // fire(0) -> cooldown(1..3) -> still high(4) stays disarmed ->
+    // drop just below band(5): arms but does NOT fire same pass ->
+    // climb back to cap(6): fires again.
+    const seq = [
+      CAP, // 0 fire
+      CAP, // 1 cooldown
+      CAP, // 2 cooldown
+      CAP, // 3 cooldown
+      CAP, // 4 disarmed, above band -> hold
+      lowBand - 1, // 5 re-arm, must NOT fire here
+      CAP, // 6 armed + at cap -> fire
+    ]
+    const { fires } = run(seq)
+    expect(fires).toEqual([0, 6])
+  })
+
+  it('does not re-arm if occupancy only drops to the band but not below it', () => {
+    const lowBand = CAP * COMPACT_REARM_FRACTION
+    // After cooldown, occupancy sits exactly at the band (not strictly
+    // below) forever -> never re-arms -> only the first fire.
+    const seq = [CAP, CAP, CAP, CAP, lowBand, lowBand, lowBand, CAP, CAP]
+    const { fires } = run(seq)
+    expect(fires).toEqual([0])
+  })
+
+  it('full healthy cycle: fire, compaction shrinks context, climbs again, fires again', () => {
+    const seq = [
+      120_000, // below cap
+      CAP, // fire (idx 1)
+      30_000, // cooldown 1 (post-compact, small)
+      35_000, // cooldown 2
+      40_000, // cooldown 3
+      45_000, // disarmed, below band -> re-arm (no fire)
+      90_000, // armed, below cap -> hold
+      CAP + 5_000, // fire again (idx 7)
+    ]
+    const { fires } = run(seq)
+    expect(fires).toEqual([1, 7])
+  })
+
+  it('never fires twice in immediate succession even with no cooldown left if still disarmed', () => {
+    // Construct a state that is past cooldown but disarmed, occupancy
+    // pegged at cap: must hold (not fire) until it drops below band.
+    const stuck: CompactState = { armed: false, cooldownTurns: 0 }
+    const { fires } = run([CAP, CAP, CAP, CAP], stuck)
+    expect(fires).toEqual([])
+  })
+})