Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

perf(server): idle-LRU eviction for agent sessions (#2812)

Andrew Mikofalvy93c2b349cf9d
diff --git a/.changeset/agent-session-idle-lru-eviction.md b/.changeset/agent-session-idle-lru-eviction.md
new file mode 100644
index 000000000..bb760279d
--- /dev/null
+++ b/.changeset/agent-session-idle-lru-eviction.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Agent write bursts across many documents no longer stall with "server busy" (503) once 256 documents have been touched. At the session cap the server now evicts the least-recently-used idle agent session — flushing its document to disk first — so large bursts stream through a bounded working set. Sessions used within the last few seconds are never evicted, and a 503 is still returned only when every session is genuinely in use. Undo history for an evicted session ends with it (same as a disconnect); a later write on that document starts a fresh session under the same agent identity, so edit attribution is unaffected. New diagnostics: an `ok.sessions.evictions_total` OpenTelemetry counter and an `agentSessionEvictions` counter on `GET /api/metrics/reconciliation`.
diff --git a/packages/app/tests/integration/agent-session-eviction.test.ts b/packages/app/tests/integration/agent-session-eviction.test.ts
new file mode 100644
index 000000000..a70a1854d
--- /dev/null
+++ b/packages/app/tests/integration/agent-session-eviction.test.ts
@@ -0,0 +1,70 @@
+/**
+ * LRU-idle session eviction against the real server stack.
+ *
+ * Proves the piece the unit suite's mock cannot: eviction's teardown is the
+ * real `DirectConnection.disconnect`, which stores the doc immediately (not
+ * debounced) before unloading — an evicted session's writes reach disk, and
+ * a fresh session re-reads them intact.
+ *
+ * @see packages/server/src/agent-sessions.eviction.test.ts — LRU/floor/undo
+ * semantics on the unit mock
+ */
+
+import { randomUUID } from 'node:crypto';
+import { AgentSessionManager, applyAgentMarkdownWrite } from '@inkeep/open-knowledge-server';
+import { afterAll, beforeAll, describe, expect, test } from 'vitest';
+import { HARNESS_BOOT_TIMEOUT_MS } from './harness-boot-timeout';
+import type { TestServer } from './test-harness';
+import { createTestServer, readTestDoc } from './test-harness';
+
+let server: TestServer;
+
+beforeAll(async () => {
+ server = await createTestServer();
+}, HARNESS_BOOT_TIMEOUT_MS);
+
+afterAll(async () => {
+ await server.cleanup();
+});
+
+describe('agent-session LRU eviction (real Hocuspocus + persistence)', () => {
+ test('evicted session state is persisted: write, evict under pressure, re-read intact', async () => {
+ // A dedicated manager over the SAME hocuspocus instance, with a tiny cap
+ // and a zero idle floor so cap pressure evicts deterministically.
+ const manager = new AgentSessionManager(server.instance.hocuspocus, {
+ maxSessions: 2,
+ minEvictableIdleMs: 0,
+ });
+
+ const docName = `evict-persist-${randomUUID()}`;
+ const content = '# Evicted Doc\n\nBytes written before eviction.\n';
+
+ const session = await manager.getSession(docName, 'agent-evict-int');
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, content, 'replace');
+ }, session.origin);
+
+ // No manual flush: the eviction path itself must persist. Fill the cap
+ // with two more distinct docs — the first create evicts our LRU session
+ // and awaits its disconnect, which stores the doc before unload.
+ await manager.getSession(`evict-fill-a-${randomUUID()}`, 'agent-evict-int');
+ await manager.getSession(`evict-fill-b-${randomUUID()}`, 'agent-evict-int');
+
+ expect(manager.hasSession(docName, 'agent-evict-int')).toBe(false);
+ expect(manager.evictionCount).toBeGreaterThanOrEqual(1);
+
+ // The write survived teardown to disk.
+ expect(readTestDoc(server.contentDir, docName)).toBe(content);
+
+ // A fresh session sees the persisted bytes and starts with a clean undo
+ // stack — the evicted session's stack died with it, never corrupting the
+ // successor.
+ const fresh = await manager.getSession(docName, 'agent-evict-int');
+ expect(fresh.dc.document.getText('source').toString()).toBe(content);
+ expect(fresh.um.undoStack.length).toBe(0);
+ // Same derived writer identity across the evict/recreate boundary.
+ expect(fresh.origin.context.session_id).toBe(session.origin.context.session_id);
+
+ await manager.closeAll();
+ });
+});
diff --git a/packages/server/src/agent-sessions.eviction.test.ts b/packages/server/src/agent-sessions.eviction.test.ts
new file mode 100644
index 000000000..6c0c3fc31
--- /dev/null
+++ b/packages/server/src/agent-sessions.eviction.test.ts
@@ -0,0 +1,309 @@
+/**
+ * LRU-idle eviction under capacity pressure.
+ *
+ * At the cap, `getSession` evicts the least-recently-used session whose idle
+ * age clears the floor instead of refusing outright — a burst of writes to
+ * many distinct docs streams through a bounded working set. When nothing is
+ * idle-eligible, behavior degrades to the pre-eviction contract
+ * (`AgentSessionCapacityError` → 503 at the HTTP boundary).
+ *
+ * Companion to `agent-sessions.test.ts` (session lifecycle) — kept separate
+ * so this file can import from `vitest` directly.
+ */
+import type { Document } from '@hocuspocus/server';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+import * as Y from 'yjs';
+import {
+ type AgentDirectConnection,
+ AgentSessionCapacityError,
+ AgentSessionManager,
+ applyAgentMarkdownWrite,
+ applyAgentUndo,
+} from './agent-sessions.ts';
+import { getMetrics, resetMetrics } from './metrics.ts';
+
+/**
+ * Minimal Hocuspocus mock (mirrors the one in `agent-sessions.test.ts`):
+ * every openDirectConnection returns a unique DC over a real per-doc Y.Doc so
+ * UndoManager creation and transacts behave. `deferCreates` lets a test hold
+ * session creation in the pending map to probe the capacity accounting.
+ */
+function createMockHocuspocus(options: { deferCreates?: boolean } = {}) {
+ const ydocs = new Map<string, Y.Doc>();
+ const pendingReleases: Array<() => void> = [];
+
+ function makeDC(docName: string): AgentDirectConnection {
+ let disconnected = false;
+ let ydoc = ydocs.get(docName);
+ if (!ydoc) {
+ ydoc = new Y.Doc();
+ ydocs.set(docName, ydoc);
+ }
+ const doc = {
+ name: docName,
+ getText: (name: string) => ydoc.getText(name),
+ getMap: (name: string) => ydoc.getMap(name),
+ getXmlFragment: (name: string) => ydoc.getXmlFragment(name),
+ transact: (fn: () => void, origin?: unknown) => ydoc.transact(fn, origin),
+ on: ydoc.on.bind(ydoc),
+ off: ydoc.off.bind(ydoc),
+ } as unknown as Document;
+ return {
+ document: doc,
+ disconnect: async () => {
+ disconnected = true;
+ },
+ isDisconnected: () => disconnected,
+ transact: () => {},
+ } as unknown as AgentDirectConnection;
+ }
+
+ return {
+ releaseAllPending(): void {
+ for (const release of pendingReleases.splice(0)) release();
+ },
+ openDirectConnection: async (docName: string): Promise<AgentDirectConnection> => {
+ if (options.deferCreates) {
+ await new Promise<void>((resolve) => {
+ pendingReleases.push(resolve);
+ });
+ }
+ return makeDC(docName);
+ },
+ };
+}
+
+let mockHocuspocus: ReturnType<typeof createMockHocuspocus>;
+
+beforeEach(() => {
+ mockHocuspocus = createMockHocuspocus();
+ resetMetrics();
+});
+
+afterEach(() => {
+ resetMetrics();
+});
+
+describe('LRU-idle eviction at the session cap', () => {
+ test('a burst of creates past the cap streams through instead of throwing 503', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 4,
+ minEvictableIdleMs: 0,
+ });
+
+ // 12 distinct docs — 3x the cap. Pre-eviction this threw
+ // AgentSessionCapacityError at doc #5; now every create succeeds.
+ for (let i = 0; i < 12; i++) {
+ await manager.getSession(`burst-doc-${i}.md`, 'agent-burst');
+ expect(manager.liveSessionCount).toBeLessThanOrEqual(4);
+ }
+
+ // The newest 4 survive; the earliest were evicted in LRU order.
+ for (let i = 8; i < 12; i++) {
+ expect(manager.hasSession(`burst-doc-${i}.md`, 'agent-burst')).toBe(true);
+ }
+ for (let i = 0; i < 8; i++) {
+ expect(manager.hasSession(`burst-doc-${i}.md`, 'agent-burst')).toBe(false);
+ }
+ expect(manager.evictionCount).toBe(8);
+
+ await manager.closeAll();
+ });
+
+ test('eviction picks the least-recently-used session — a getSession touch protects it', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 3,
+ minEvictableIdleMs: 0,
+ });
+
+ await manager.getSession('doc-a.md', 'agent-lru');
+ await manager.getSession('doc-b.md', 'agent-lru');
+ await manager.getSession('doc-c.md', 'agent-lru');
+
+ // Touch A — B becomes the LRU.
+ await manager.getSession('doc-a.md', 'agent-lru');
+
+ await manager.getSession('doc-d.md', 'agent-lru');
+
+ expect(manager.hasSession('doc-b.md', 'agent-lru')).toBe(false);
+ expect(manager.hasSession('doc-a.md', 'agent-lru')).toBe(true);
+ expect(manager.hasSession('doc-c.md', 'agent-lru')).toBe(true);
+ expect(manager.hasSession('doc-d.md', 'agent-lru')).toBe(true);
+
+ await manager.closeAll();
+ });
+
+ test('a getLiveSession read also refreshes recency', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 3,
+ minEvictableIdleMs: 0,
+ });
+
+ await manager.getSession('doc-a.md', 'agent-read');
+ await manager.getSession('doc-b.md', 'agent-read');
+ await manager.getSession('doc-c.md', 'agent-read');
+
+ // Read A (the burst-diff path) — B becomes the LRU.
+ expect(manager.getLiveSession('doc-a.md', 'agent-read')).toBeDefined();
+
+ await manager.getSession('doc-d.md', 'agent-read');
+
+ expect(manager.hasSession('doc-b.md', 'agent-read')).toBe(false);
+ expect(manager.hasSession('doc-a.md', 'agent-read')).toBe(true);
+
+ await manager.closeAll();
+ });
+
+ test('sessions younger than the idle floor are never evicted — capacity error is preserved', async () => {
+ // A just-used session may belong to an in-flight request; with a floor
+ // higher than the test's runtime nothing is eligible and the cap
+ // degrades to the pre-eviction 503 contract.
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 2,
+ minEvictableIdleMs: 60_000,
+ });
+
+ await manager.getSession('doc-a.md', 'agent-floor');
+ await manager.getSession('doc-b.md', 'agent-floor');
+
+ await expect(manager.getSession('doc-c.md', 'agent-floor')).rejects.toBeInstanceOf(
+ AgentSessionCapacityError,
+ );
+
+ // Nothing was torn down under the (conceptually in-flight) sessions.
+ expect(manager.hasSession('doc-a.md', 'agent-floor')).toBe(true);
+ expect(manager.hasSession('doc-b.md', 'agent-floor')).toBe(true);
+ expect(manager.evictionCount).toBe(0);
+
+ await manager.closeAll();
+ });
+
+ test('existing-session reuse at the cap neither evicts nor throws', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 2,
+ minEvictableIdleMs: 0,
+ });
+
+ const a = await manager.getSession('doc-a.md', 'agent-reuse');
+ await manager.getSession('doc-b.md', 'agent-reuse');
+
+ const aAgain = await manager.getSession('doc-a.md', 'agent-reuse');
+ expect(aAgain).toBe(a);
+ expect(manager.evictionCount).toBe(0);
+ expect(manager.liveSessionCount).toBe(2);
+
+ await manager.closeAll();
+ });
+
+ test('eviction runs the disconnect teardown spine: DC disconnected, UM destroyed, entry removed', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 1,
+ minEvictableIdleMs: 0,
+ });
+
+ const victim = await manager.getSession('doc-victim.md', 'agent-teardown');
+ await manager.getSession('doc-new.md', 'agent-teardown');
+
+ expect(manager.hasSession('doc-victim.md', 'agent-teardown')).toBe(false);
+ expect((victim.dc as unknown as { isDisconnected: () => boolean }).isDisconnected()).toBe(true);
+ // um.destroy() ran — the stack is empty and no longer tracking.
+ expect(victim.um.undoStack.length).toBe(0);
+
+ await manager.closeAll();
+ });
+
+ test('undo after eviction fails cleanly: hasSession is false and a fresh session has no undo stack', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 1,
+ minEvictableIdleMs: 0,
+ });
+
+ const session = await manager.getSession('doc-undo.md', 'agent-undo-evict');
+ session.dc.document.transact(() => {
+ applyAgentMarkdownWrite(session.dc.document, '# Before eviction\n', 'replace');
+ }, session.origin);
+ session.um.stopCapturing();
+ expect(session.um.undoStack.length).toBeGreaterThan(0);
+
+ // Pressure-evict by creating a session on another doc.
+ await manager.getSession('doc-other.md', 'agent-undo-evict');
+
+ // The HTTP undo handler guards on hasSession before resolving a session;
+ // an evicted (docName, agentId) reads as absent → the handler's
+ // no-active-session refusal, never a write against torn-down state.
+ expect(manager.hasSession('doc-undo.md', 'agent-undo-evict')).toBe(false);
+
+ // A later getSession mints a FRESH session: empty undo stack, undo is a
+ // clean no-op (returns false), document content untouched.
+ const fresh = await manager.getSession('doc-undo.md', 'agent-undo-evict');
+ expect(fresh).not.toBe(session);
+ expect(fresh.um.undoStack.length).toBe(0);
+ expect(applyAgentUndo(fresh, 'session')).toBe(false);
+ expect(fresh.dc.document.getText('source').toString()).toBe('# Before eviction\n');
+
+ await manager.closeAll();
+ });
+
+ test('writer identity is continuous across eviction: same session_id, fresh origin object', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 1,
+ minEvictableIdleMs: 0,
+ });
+
+ const before = await manager.getSession('doc-attr.md', 'agent-85aabbcc');
+ await manager.getSession('doc-fill.md', 'agent-85aabbcc');
+ const after = await manager.getSession('doc-attr.md', 'agent-85aabbcc');
+
+ // resolveWriterFromOrigin derives the shadow-repo writerId from
+ // context.session_id — identical before/after, so attribution chains
+ // continue under the same `agent-<id>` writer.
+ expect(after.origin.context.session_id).toBe(before.origin.context.session_id);
+ expect(after.origin.context.session_id).toBe('85aabbcc');
+ // The frozen origin object itself is fresh (Set-identity for the new
+ // session's UndoManager trackedOrigins).
+ expect(after.origin).not.toBe(before.origin);
+
+ await manager.closeAll();
+ });
+
+ test('pending (in-flight) session creations are never evicted and hold their capacity slot', async () => {
+ const deferred = createMockHocuspocus({ deferCreates: true });
+ const manager = new AgentSessionManager(deferred as never, {
+ maxSessions: 1,
+ minEvictableIdleMs: 0,
+ });
+
+ // Start a create and leave it pending — it occupies the only slot from
+ // the pending map, where eviction cannot reach it.
+ const pending = manager.getSession('doc-pending.md', 'agent-pending');
+
+ // A second distinct create finds the slot held by a pending entry and
+ // nothing evictable in the live map → capacity refusal.
+ await expect(manager.getSession('doc-other.md', 'agent-pending')).rejects.toBeInstanceOf(
+ AgentSessionCapacityError,
+ );
+
+ deferred.releaseAllPending();
+ const session = await pending;
+ expect(session.docName).toBe('doc-pending.md');
+ expect(manager.hasSession('doc-pending.md', 'agent-pending')).toBe(true);
+
+ await manager.closeAll();
+ });
+
+ test('evictions increment the in-process metrics counter', async () => {
+ const manager = new AgentSessionManager(mockHocuspocus as never, {
+ maxSessions: 1,
+ minEvictableIdleMs: 0,
+ });
+
+ expect(getMetrics().agentSessionEvictions).toBe(0);
+ await manager.getSession('doc-m1.md', 'agent-metrics');
+ await manager.getSession('doc-m2.md', 'agent-metrics');
+ await manager.getSession('doc-m3.md', 'agent-metrics');
+ expect(getMetrics().agentSessionEvictions).toBe(2);
+ expect(manager.evictionCount).toBe(2);
+
+ await manager.closeAll();
+ });
+});
diff --git a/packages/server/src/agent-sessions.ts b/packages/server/src/agent-sessions.ts
index ba6c9e9a0..df0bac35c 100644
--- a/packages/server/src/agent-sessions.ts
+++ b/packages/server/src/agent-sessions.ts
@@ -43,8 +43,9 @@ import { getDocExtension, stripDocExtension } from './doc-extensions.ts';
import { FrontmatterMalformedError } from './frontmatter-malformed-error.ts';
import { recordFrontmatterEditSurface } from './frontmatter-telemetry.ts';
import { getLogger } from './logger.ts';
+import { incrementAgentSessionEvictions } from './metrics.ts';
import type { PairedWriteOrigin } from './server-observers.ts';
-import { setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
+import { getMeter, setActiveSpanAttributes, withSpanSync } from './telemetry.ts';
/**
* The post-write content-divergence signal. Defined in (and produced by) the
@@ -556,6 +557,13 @@ interface SessionRecord {
um: Y.UndoManager;
agentId: string;
docName: string;
+ /**
+ * Recency stamp (epoch ms), maintained exclusively by AgentSessionManager:
+ * refreshed on every `getSession` / `getLiveSession` hit. The manager's
+ * sessions map mirrors it in insertion order (a touch re-inserts the
+ * entry), so the map's first entry is always the LRU eviction candidate.
+ */
+ lastUsedAt: number;
}
/**
@@ -637,11 +645,35 @@ function createUndoOrigin(sessionId: string, agentType?: string): PairedWriteOri
*
* 256 leaves comfortable headroom for realistic local workflows (a handful
* of MCP clients across dozens of docs) while keeping the worst-case
- * footprint bounded. Hitting the cap surfaces as a 503 at the HTTP boundary
- * rather than silently growing memory or crashing the process.
+ * footprint bounded. At capacity the manager first evicts the
+ * least-recently-used idle session (see `MIN_EVICTABLE_IDLE_MS`) so a burst
+ * of writes across many distinct docs streams through a bounded working set;
+ * only when no session is idle-eligible does the cap surface as a 503 at the
+ * HTTP boundary.
*/
export const MAX_AGENT_SESSIONS = 256;
+/**
+ * Minimum idle age before a live session becomes eviction-eligible under
+ * capacity pressure.
+ *
+ * The floor guards in-flight handlers: every HTTP request re-resolves its
+ * session via `getSession` at entry (refreshing recency), so a session
+ * younger than the floor may still be inside a request whose transact has
+ * not run yet. Evicting it would null the DirectConnection under the
+ * handler (`dc.document` becomes null on disconnect) and destroy its
+ * UndoManager mid-flight. Past the floor a session is quiescent — agent
+ * write handlers flush the doc to disk before responding, so nothing is in
+ * flight and nothing is unpersisted.
+ *
+ * Small by design: a burst that fills the cap ages its LRU session by
+ * roughly (cap x per-write latency), and every write awaits its disk flush,
+ * so realistic bursts are well past the floor by the time eviction is
+ * needed. In-code constant, not user config; tests override via the
+ * constructor option.
+ */
+export const MIN_EVICTABLE_IDLE_MS = 5_000;
+
/**
* Thrown by `AgentSessionManager.getSession` when creating a new session
* would exceed `MAX_AGENT_SESSIONS`. HTTP handlers catch this and translate
@@ -656,17 +688,41 @@ export class AgentSessionCapacityError extends Error {
}
}
+/** Lazy, process-wide eviction counter — instrument is created on first use so
+ * module load stays side-effect-free when OTel is disabled (no-op meter). */
+let _evictionCounter: ReturnType<ReturnType<typeof getMeter>['createCounter']> | null = null;
+function evictionCounter(): ReturnType<ReturnType<typeof getMeter>['createCounter']> {
+ _evictionCounter ||= getMeter().createCounter('ok.sessions.evictions_total', {
+ description:
+ 'Agent sessions evicted (LRU-idle) under capacity pressure to admit a new session. Sustained growth alongside ok.sessions.active pinned at ok.sessions.limit means the working set exceeds the cap.',
+ unit: '{sessions}',
+ });
+ return _evictionCounter;
+}
+
export class AgentSessionManager {
+ /**
+ * Live sessions in recency order: every touch re-inserts the entry, so
+ * iteration starts at the least-recently-used session. Eviction relies on
+ * this — do not add write paths that bypass `touchSession`.
+ */
private sessions = new Map<string, SessionRecord>();
/** In-flight promise dedup — concurrent first-calls share one pending openDirectConnection. */
private pendingSessions = new Map<string, Promise<SessionRecord>>();
private hocuspocus: Hocuspocus;
/** Hard cap on simultaneous live sessions. Override is for tests only. */
private readonly maxSessions: number;
+ /** Idle floor for eviction eligibility. Override is for tests only. */
+ private readonly minEvictableIdleMs: number;
+ private evictions = 0;
- constructor(hocuspocus: Hocuspocus, options: { maxSessions?: number } = {}) {
+ constructor(
+ hocuspocus: Hocuspocus,
+ options: { maxSessions?: number; minEvictableIdleMs?: number } = {},
+ ) {
this.hocuspocus = hocuspocus;
this.maxSessions = options.maxSessions ?? MAX_AGENT_SESSIONS;
+ this.minEvictableIdleMs = options.minEvictableIdleMs ?? MIN_EVICTABLE_IDLE_MS;
}
/** Number of live sessions currently retained. Read-only occupancy probe. */
@@ -679,6 +735,21 @@ export class AgentSessionManager {
return this.maxSessions;
}
+ /** Sessions evicted under capacity pressure since construction. */
+ public get evictionCount(): number {
+ return this.evictions;
+ }
+
+ /**
+ * Refresh a session's recency: stamp `lastUsedAt` and re-insert the entry
+ * so the map's iteration order stays LRU-first.
+ */
+ private touchSession(key: string, session: SessionRecord): void {
+ session.lastUsedAt = Date.now();
+ this.sessions.delete(key);
+ this.sessions.set(key, session);
+ }
+
private sessionKey(docName: string, agentId: string): string {
return `${docName}\0${agentId}`;
}
@@ -711,7 +782,13 @@ export class AgentSessionManager {
* the existence check.
*/
public getLiveSession(docName: string, agentId: string): SessionRecord | undefined {
- return this.sessions.get(this.sessionKey(docName, agentId));
+ const key = this.sessionKey(docName, agentId);
+ const session = this.sessions.get(key);
+ // A read is a use: the burst-diff caller walks the session's UM stacks
+ // right after this returns, so refreshing recency keeps eviction from
+ // tearing the session down under the read.
+ if (session) this.touchSession(key, session);
+ return session;
}
/**
@@ -739,7 +816,10 @@ export class AgentSessionManager {
const key = this.sessionKey(docName, agentId);
const existing = this.sessions.get(key);
- if (existing) return existing;
+ if (existing) {
+ this.touchSession(key, existing);
+ return existing;
+ }
// Reuse in-flight promise if a concurrent first-call is already pending
const inflight = this.pendingSessions.get(key);
@@ -752,12 +832,21 @@ export class AgentSessionManager {
// entry. Existing-session lookups returned above. Counts both resolved
// and pending so a concurrent burst of distinct ids cannot race past
// the cap before any of them lands in `sessions`.
- if (this.sessions.size + this.pendingSessions.size >= this.maxSessions) {
- log.warn(
- { docName, agentId, limit: this.maxSessions },
- '[agent-session] session capacity reached, refusing new session',
- );
- throw new AgentSessionCapacityError(this.maxSessions);
+ //
+ // At capacity, evict LRU idle sessions until a slot frees so a burst of
+ // writes to many distinct docs streams through a bounded working set
+ // instead of stalling at the cap. When nothing is idle-eligible (every
+ // session touched within the idle floor), degrade to the capacity
+ // refusal — an in-flight handler is never torn down under itself.
+ while (this.sessions.size + this.pendingSessions.size >= this.maxSessions) {
+ const evictedKey = await this.evictLruIdleSession();
+ if (evictedKey === null) {
+ log.warn(
+ { docName, agentId, limit: this.maxSessions },
+ '[agent-session] session capacity reached, refusing new session',
+ );
+ throw new AgentSessionCapacityError(this.maxSessions);
+ }
}
const promise = this._createSession(docName, agentId, identity);
@@ -866,7 +955,57 @@ export class AgentSessionManager {
`[agent-session] Created session for: ${docName} / ${agentId}`,
);
- return { dc, origin, undoOrigin, um, agentId, docName };
+ return { dc, origin, undoOrigin, um, agentId, docName, lastUsedAt: Date.now() };
+ }
+
+ /**
+ * Evict the least-recently-used idle session to relieve capacity pressure.
+ * Returns the evicted session key, or `null` when nothing is eligible.
+ *
+ * The sessions map is kept in recency order (every touch re-inserts), so
+ * the first entry IS the LRU candidate — and if it is younger than the
+ * idle floor, every other entry is younger still, so the scan is O(1).
+ *
+ * The entry is removed from the map synchronously BEFORE the async
+ * teardown so a concurrent create cannot select the same victim. Teardown
+ * IS the existing disconnect spine (`cleanupSession`: um.destroy +
+ * dc.disconnect); Hocuspocus's `DirectConnection.disconnect` stores the
+ * doc immediately (not debounced) before unloading it, so evicted state
+ * reaches disk exactly as it does on keepalive teardown. Because the map
+ * delete frees the slot before the teardown settles, concurrent creates
+ * can transiently hold more DirectConnections than the cap while
+ * evictions drain — bounded by the number of evictable sessions and
+ * decaying as each disconnect completes.
+ *
+ * Eviction destroys the session's UndoManager stack — identical to
+ * disconnect teardown, where the stack was only ever reachable while the
+ * session lived. A later undo for the evicted (docName, agentId) finds no
+ * session (`hasSession` false → the handler's no-active-session
+ * refusal); a later write mints a fresh session whose origin carries the
+ * same session_id, so the derived writer id (`agent-<id>`) and
+ * shadow-repo attribution stay continuous across eviction.
+ */
+ private async evictLruIdleSession(): Promise<string | null> {
+ const first = this.sessions.entries().next();
+ if (first.done) return null;
+ const [key, session] = first.value;
+ const idleMs = Date.now() - session.lastUsedAt;
+ if (idleMs < this.minEvictableIdleMs) return null;
+
+ this.sessions.delete(key);
+ await this.cleanupSession(key, session, {
+ docName: session.docName,
+ agentId: session.agentId,
+ evicted: true,
+ });
+ this.evictions++;
+ incrementAgentSessionEvictions();
+ evictionCounter().add(1);
+ log.info(
+ { docName: session.docName, agentId: session.agentId, idleMs },
+ '[agent-session] Evicted LRU idle session under capacity pressure',
+ );
+ return key;
}
/** Check if a session exists without creating one. */
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index 8e771d423..dd9ae049b 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -25,6 +25,7 @@ export {
colorFromSeed,
iconFromClientName,
MAX_AGENT_SESSIONS,
+ MIN_EVICTABLE_IDLE_MS,
} from './agent-sessions.ts';
export {
__getShowAllWalkStatsForTesting,
diff --git a/packages/server/src/metrics.ts b/packages/server/src/metrics.ts
index 837f2a74d..a17279a72 100644
--- a/packages/server/src/metrics.ts
+++ b/packages/server/src/metrics.ts
@@ -181,6 +181,12 @@ export interface ReconciliationMetrics {
* agent-write handlers only AFTER a successful recordContributor;
* UI-driven rollback/rename without agentId does NOT increment. */
agentWriteCalls: number;
+ /** Agent sessions evicted (LRU-idle) under capacity pressure so a new
+ * (docName, agentId) session could be admitted under
+ * `MAX_AGENT_SESSIONS`. Steady growth alongside 503s means the live
+ * working set genuinely exceeds the cap; growth WITHOUT 503s means
+ * eviction is absorbing bursts as designed. */
+ agentSessionEvictions: number;
/** Agent-write calls that carried a non-empty summary through
* normalizeSummary — numerator for the summary-adoption metric.
* Adoption rate = summariesProvided / agentWriteCalls. */
@@ -461,6 +467,7 @@ const counters: ReconciliationMetrics = {
effectDiffCaptureFailures: 0,
agentPresenceMutationErrors: 0,
agentWriteCalls: 0,
+ agentSessionEvictions: 0,
summariesProvided: 0,
summariesTruncated: 0,
agentPatchFindMismatches: 0,
@@ -568,6 +575,10 @@ export function incrementAgentWriteCalls(): void {
counters.agentWriteCalls++;
}
+export function incrementAgentSessionEvictions(): void {
+ counters.agentSessionEvictions++;
+}
+
export function incrementSummariesProvided(): void {
counters.summariesProvided++;
}
@@ -858,6 +869,7 @@ export function resetMetrics(): void {
counters.effectDiffCaptureFailures = 0;
counters.agentPresenceMutationErrors = 0;
counters.agentWriteCalls = 0;
+ counters.agentSessionEvictions = 0;
counters.summariesProvided = 0;
counters.summariesTruncated = 0;
counters.agentPatchFindMismatches = 0;