switchroom 0.12.15 → 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,
@@ -245,7 +247,7 @@ import { shouldSweepChatAtBoot } from './boot-sweep-filter.js'
 import { createIpcServer, type IpcClient, type IpcServer } from './ipc-server.js'
 import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
-import { createPendingInboundBuffer, redeliverBufferedInbound } from './pending-inbound-buffer.js'
+import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
 import { createPendingPermissionBuffer } from './pending-permission-decisions.js'
 import {
   buildVaultGrantApprovedInbound,
@@ -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.
@@ -3272,6 +3379,48 @@ const ipcServer: IpcServer = createIpcServer({
   log: (msg) => process.stderr.write(`telegram gateway: ipc — ${msg}\n`),
 })
 
+// ─── Opportunistic idle-drain of pendingInboundBuffer ─────────────────────
+// pendingInboundBuffer otherwise drains only on (a) bridge re-register
+// (onClientRegistered) or (b) the silence-poke framework fallback
+// clearing a wedged turn (#1546). NEITHER fires when a message is
+// buffered during a bridge-IPC flap that then settles with no
+// subsequent clean re-register AND claude is idle (no active turn →
+// silence-poke never arms). The message orphans until a manual restart
+// (finn, 2026-05-19 — buffered "verify with mff-query.py cashflow"
+// while idle; last `bridge registered` predated the buffer push, so
+// onClientRegistered's drain never ran for it).
+//
+// This is the third drain trigger. It's gated to be zero-cost and
+// zero-churn: skip entirely when nothing is buffered (one Map.get, no
+// log) or when the bridge isn't alive (exactly sendToAgent's own
+// guard — so we never drain into a dead bridge and re-buffer/log-spin).
+// Only when there IS a buffered message AND a live bridge do we reuse
+// the #1546 `redeliverBufferedInbound` (lossless: re-buffers any
+// per-message miss). A message delivered while a turn is active is
+// queued normally by the bridge — same as a live arrival, not lost.
+const IDLE_DRAIN_INTERVAL_MS = 5000
+if (!STATIC) {
+  setInterval(() => {
+    const selfAgent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+    const r = idleDrainTick(
+      pendingInboundBuffer,
+      selfAgent,
+      () => {
+        const c = ipcServer.getClient(selfAgent)
+        return c != null && c.isAlive()
+      },
+      (m) => ipcServer.sendToAgent(selfAgent, m),
+    )
+    if (r != null && r.redelivered > 0) {
+      process.stderr.write(
+        `telegram gateway: idle-drain flushed ${r.redelivered}/${r.drained} ` +
+        `buffered inbound for ${selfAgent}` +
+        `${r.rebuffered > 0 ? ` (${r.rebuffered} re-buffered)` : ''}\n`,
+      )
+    }
+  }, IDLE_DRAIN_INTERVAL_MS).unref()
+}
+
 // ─── Tool execution ──────────────────────────────────────────────────────
 
 /** Allowlisted tool names that bridges may invoke via IPC. Prevents a rogue

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/pending-inbound-buffer.ts

@@ -93,6 +93,38 @@ export function redeliverBufferedInbound(
   return { drained: pending.length, redelivered, rebuffered }
 }
 
+/**
+ * One opportunistic idle-drain tick. The third drain trigger, beside
+ * `onClientRegistered` (bridge re-register) and the silence-poke
+ * wedge-clear (#1546). Closes the orphan gap those two miss: a message
+ * buffered during a bridge-IPC flap that settles with no subsequent
+ * clean re-register while claude is idle (no turn → no silence-poke)
+ * — it would otherwise sit until a manual restart (finn, 2026-05-19).
+ *
+ * Gated to be zero-cost / zero-churn so it can run on a short timer:
+ *   - empty buffer → return null (one Map.get, NO drain, NO log)
+ *   - bridge not alive → return null (never drain into a dead bridge,
+ *     which would re-buffer+log-spin every tick; onClientRegistered
+ *     will drain on the eventual reconnect instead)
+ *   - otherwise → `redeliverBufferedInbound` (lossless: re-buffers any
+ *     per-message miss). A message delivered mid-turn is queued
+ *     normally by the bridge, same as a live arrival — not lost.
+ *
+ * Returns the redeliver counts only when it actually ran, else null
+ * (so the caller logs only on a real flush).
+ */
+export function idleDrainTick(
+  buffer: PendingInboundBuffer,
+  agent: string,
+  isBridgeAlive: () => boolean,
+  send: (msg: InboundMessage) => boolean,
+): { drained: number; redelivered: number; rebuffered: number } | null {
+  if (!agent) return null
+  if (buffer.depth(agent) === 0) return null
+  if (!isBridgeAlive()) return null
+  return redeliverBufferedInbound(buffer, agent, send)
+}
+
 export function createPendingInboundBuffer(
   opts: PendingInboundBufferOptions = {},
 ): PendingInboundBuffer {

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/pending-inbound-buffer.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest'
-import { createPendingInboundBuffer, redeliverBufferedInbound, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
+import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick, DEFAULT_PENDING_INBOUND_CAP } from '../gateway/pending-inbound-buffer.js'
 import type { InboundMessage } from '../gateway/ipc-protocol.js'
 
 function inbound(source: string, ts = Date.now()): InboundMessage {
@@ -200,3 +200,50 @@ describe('redeliverBufferedInbound — wedge-clear self-heal (fleet-update incid
     expect(buf.depth('clerk')).toBe(1) // untouched
   })
 })
+
+describe('idleDrainTick — the 3rd drain trigger (finn orphan gap, 2026-05-19)', () => {
+  it('no-op (returns null, no send) when the buffer is empty', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    let sent = 0
+    const r = idleDrainTick(buf, 'finn', () => true, () => { sent++; return true })
+    expect(r).toBeNull()
+    expect(sent).toBe(0)
+  })
+
+  it('no-op (returns null) when bridge is NOT alive — never drains into a dead bridge', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('finn', inbound('user', 1))
+    let sent = 0
+    const r = idleDrainTick(buf, 'finn', () => false, () => { sent++; return true })
+    expect(r).toBeNull()
+    expect(sent).toBe(0)
+    expect(buf.depth('finn')).toBe(1) // untouched — onClientRegistered will get it on reconnect
+  })
+
+  it('flushes the buffer when bridge is alive AND something is buffered (the finn fix)', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('finn', inbound('user', 2013)) // the orphaned "verify with mff-query.py" class
+    const seen: number[] = []
+    const r = idleDrainTick(buf, 'finn', () => true, (m) => { seen.push(m.messageId as number); return true })
+    expect(r).toEqual({ drained: 1, redelivered: 1, rebuffered: 0 })
+    expect(seen).toEqual([2013])
+    expect(buf.depth('finn')).toBe(0)
+  })
+
+  it('is lossless — a delivery miss re-buffers, returns null on empty agent', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    buf.push('finn', inbound('user', 1))
+    const r = idleDrainTick(buf, 'finn', () => true, () => false)
+    expect(r).toEqual({ drained: 1, redelivered: 0, rebuffered: 1 })
+    expect(buf.depth('finn')).toBe(1) // nothing lost
+    expect(idleDrainTick(buf, '', () => true, () => true)).toBeNull() // empty agent guard
+  })
+
+  it('checks depth BEFORE isBridgeAlive — empty buffer never probes the bridge', () => {
+    const buf = createPendingInboundBuffer({ log: () => {} })
+    let probed = false
+    const r = idleDrainTick(buf, 'finn', () => { probed = true; return true }, () => true)
+    expect(r).toBeNull()
+    expect(probed).toBe(false) // cheap path: Map.get only, no bridge probe, no log
+  })
+})

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([])
+  })
+})