Skip to content

Build your personal knowledge base with Trilium Notes

fix(llm): address the keep-alive review findings

Elian Dorand2d0c84d04fb
diff --git a/apps/server/src/services/llm/providers/acp_agent.ts b/apps/server/src/services/llm/providers/acp_agent.ts
index 384376e6c2..3bde5af05d 100644
--- a/apps/server/src/services/llm/providers/acp_agent.ts
+++ b/apps/server/src/services/llm/providers/acp_agent.ts
@@ -151,6 +151,14 @@ interface ProviderState {
const stateByProvider = new Map<string, ProviderState>();
+/** Clients whose agent advertised `session/close` in its `initialize` response. */
+const sessionClosers = new WeakSet<AcpClient>();
+
+/** The part of the `initialize` response Trilium reads. */
+interface AcpInitializeResult {
+ agentCapabilities?: { sessionCapabilities?: { close?: unknown } };
+}
+
/** For tests: stop every pooled agent and forget every provider's sessions, catalog and agent cwd. */
export function resetAcpAgentStateForTests(): void {
for (const state of stateByProvider.values()) {
@@ -379,11 +387,14 @@ export abstract class AcpAgentProvider implements LlmProvider {
const resumable = stored?.noteToolsEnabled === noteToolsEnabled ? resume : undefined;
let sessionId: string | undefined;
let sessionModels: AcpSessionModelState | undefined;
- if (resumable && stored?.generation === acquired.generation) {
+ const isLive = resumable !== undefined && stored?.generation === acquired.generation;
+ // Only opening or loading a session names its MCP servers.
+ const mcpServers = isLive ? [] : await buildMcpServersConfig(noteToolsEnabled);
+ if (isLive) {
// The session is still loaded in this process, so the turn
// prompts it directly. The CLIs reject `session/load` for it.
sessionId = resumable;
- sessionModels = stored.models;
+ sessionModels = stored?.models;
} else if (resumable) {
// The process that held the session ended. `session/load`
// replays its history as notifications, which the pool drops
@@ -391,7 +402,7 @@ export abstract class AcpAgentProvider implements LlmProvider {
try {
const loaded = await client.request<{ models?: AcpSessionModelState } | null>(
"session/load",
- { sessionId: resumable, cwd: this.agentCwd(), mcpServers: await buildMcpServersConfig(noteToolsEnabled) },
+ { sessionId: resumable, cwd: this.agentCwd(), mcpServers },
SESSION_TIMEOUT_MS
);
sessionId = resumable;
@@ -402,7 +413,7 @@ export abstract class AcpAgentProvider implements LlmProvider {
}
if (!sessionId) {
- const created = await this.createSession(client, { cwd: this.agentCwd(), mcpServers: await buildMcpServersConfig(noteToolsEnabled) }, false, SESSION_TIMEOUT_MS);
+ const created = await this.createSession(client, { cwd: this.agentCwd(), mcpServers }, false, SESSION_TIMEOUT_MS);
sessionId = created.sessionId;
sessionModels = created.models;
}
@@ -573,6 +584,10 @@ export abstract class AcpAgentProvider implements LlmProvider {
} finally {
if (attachedSession) {
pool.detach(attachedSession);
+ // The title session is used once, and the process outlives it.
+ if (lease && sessionClosers.has(lease.client)) {
+ await this.closeAgentSession(lease.client, attachedSession);
+ }
}
if (lease) {
pool.release();
@@ -580,6 +595,15 @@ export abstract class AcpAgentProvider implements LlmProvider {
}
}
+ /** Ask the agent to drop a session it no longer needs, logging a refusal. */
+ private async closeAgentSession(client: AcpClient, sessionId: string): Promise<void> {
+ try {
+ await client.request("session/close", { sessionId }, INIT_TIMEOUT_MS);
+ } catch (err) {
+ getLog().info(`${this.logLabel}: session/close failed (${describeError(err)}).`);
+ }
+ }
+
/** Start the pooled agent, answering each permission request with its turn's configuration. */
private connect(connection: AcpPoolConnection): Promise<AcpClient> {
return this.startClient(connection.onNotification, {
@@ -615,7 +639,7 @@ export abstract class AcpAgentProvider implements LlmProvider {
onExit: options.onExit
});
try {
- await client.request(
+ const initialized = await client.request<AcpInitializeResult | null>(
"initialize",
{
protocolVersion: 1,
@@ -626,6 +650,9 @@ export abstract class AcpAgentProvider implements LlmProvider {
},
INIT_TIMEOUT_MS
);
+ if (initialized?.agentCapabilities?.sessionCapabilities?.close) {
+ sessionClosers.add(client);
+ }
} catch (err) {
client.dispose();
throw err;
diff --git a/apps/server/src/services/llm/providers/claude_agent.spec.ts b/apps/server/src/services/llm/providers/claude_agent.spec.ts
index b741055d91..b76dc5c8c1 100644
--- a/apps/server/src/services/llm/providers/claude_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.spec.ts
@@ -1,6 +1,8 @@
import type { LlmStreamChunk } from "@triliumnext/commons";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ClaudeSession } from "./claude_session_pool.js";
+
const queryMock = vi.hoisted(() => vi.fn());
const errorLogMock = vi.hoisted(() => vi.fn());
/** Streaming-input-only Query controls the session pool drives. */
@@ -52,7 +54,7 @@ const spawnMock = vi.hoisted(() => vi.fn());
vi.mock("child_process", () => ({ spawn: spawnMock }));
const { buildSeededPrompt, buildSubscriptionModelList, ClaudeAgentProvider, hashTranscript, resetAgentCwdForTests, resetSubscriptionModelCacheForTests } = await import("./claude_agent.js");
-const { resetClaudeSessionPoolForTests } = await import("./claude_session_pool.js");
+const { MAX_WARM_SESSIONS, Pushable, releaseSession, rememberSession: rememberWarmSession, resetClaudeSessionPoolForTests } = await import("./claude_session_pool.js");
type PushablePrompt = { pending: readonly { message: { role: string; content: unknown[] } }[] };
/**
@@ -959,6 +961,56 @@ describe("ClaudeAgentProvider.chatChunks", () => {
const fillerCall = queryMock.mock.calls[queryMock.mock.calls.length - 1][0];
expect(fillerCall.options.resume).toBe("sess-199");
});
+
+ it("closes a session whose stream failed mid-turn instead of handing it to the next turn", async () => {
+ const provider = new ClaudeAgentProvider();
+ const config = { chatNoteId: "note-broken" };
+ const followUp = [
+ { role: "user" as const, content: "q1" },
+ { role: "assistant" as const, content: "a" },
+ { role: "user" as const, content: "q2" }
+ ];
+ // One stream: the first turn completes, the second fails partway.
+ queryMock.mockImplementation(() => Object.assign((async function* () {
+ yield textDelta("a");
+ yield successResult("sess-B");
+ yield textDelta("partial");
+ throw new Error("stream broke");
+ })(), { setModel: setModelMock, close: closeMock }));
+ await collect(provider.chatChunks([{ role: "user", content: "q1" }], config));
+
+ const failed = await collect(provider.chatChunks(followUp, config));
+ expect(failed.some(c => c.type === "error")).toBe(true);
+ expect(closeMock).toHaveBeenCalledTimes(1);
+
+ // A retry on the same history starts a new query.
+ scriptAgent([textDelta("b"), successResult("sess-B")]);
+ const retried = await collect(provider.chatChunks(followUp, config));
+ expect(queryMock).toHaveBeenCalledTimes(2);
+ expect(retried).toContainEqual({ type: "text", content: "b" });
+ });
+
+ it("keeps to the warm-session cap by closing idle sessions behind a busy oldest one", () => {
+ const fakeSession = (): ClaudeSession => ({
+ query: { close: vi.fn() } as unknown as ClaudeSession["query"],
+ input: new Pushable(),
+ fingerprint: "",
+ closed: false,
+ busy: false
+ });
+ const busy = fakeSession();
+ rememberWarmSession("busy", busy);
+ const idle: ClaudeSession[] = [];
+ for (let i = 0; i < MAX_WARM_SESSIONS; i++) {
+ const session = fakeSession();
+ rememberWarmSession(`idle-${i}`, session);
+ releaseSession(`idle-${i}`, session);
+ idle.push(session);
+ }
+
+ expect(busy.closed).toBe(false);
+ expect(idle.map(s => s.closed)).toEqual([true, ...Array(MAX_WARM_SESSIONS - 1).fill(false)]);
+ });
});
describe("generateTitle", () => {
diff --git a/apps/server/src/services/llm/providers/claude_agent.ts b/apps/server/src/services/llm/providers/claude_agent.ts
index 6eaf3f0bb1..6f3b989caa 100644
--- a/apps/server/src/services/llm/providers/claude_agent.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.ts
@@ -381,6 +381,8 @@ export class ClaudeAgentProvider implements LlmProvider {
let assistantText = "";
/** The session this turn is driving, released (not closed) at the end. */
let held: ClaudeSession | undefined;
+ /** Set once the turn reaches its `result`; only then is the session in a known state. */
+ let turnComplete = false;
// tool_use id → name, for labelling results; also serves as the guard
// that only results belonging to *this* turn's tool calls are emitted.
const toolNamesById = new Map<string, string>();
@@ -450,7 +452,6 @@ export class ClaudeAgentProvider implements LlmProvider {
// Manual iteration on purpose: `for await (…) { break }` calls
// iterator.return(), which closes the query and kills the process
// this whole pool exists to keep warm.
- let turnComplete = false;
for (;;) {
const next = await active.query.next();
if (next.done) {
@@ -610,13 +611,13 @@ export class ClaudeAgentProvider implements LlmProvider {
yield { type: "error", error: describeAgentError(error) };
} finally {
signal?.removeEventListener("abort", onAbort);
- const reusable = held && config.chatNoteId && !held.closed && !signal?.aborted;
+ const reusable = held && config.chatNoteId && turnComplete && !held.closed && !signal?.aborted;
if (reusable && held && config.chatNoteId) {
// Keep the subprocess warm; the pool reaps it when idle.
releaseSession(config.chatNoteId, held);
} else {
- // A cancelled turn stops mid-stream, so the session's real
- // state is unknown and the SDK may be wedged mid-`next()`
+ // A cancelled or failed turn stops mid-stream, so the session's
+ // real state is unknown and the SDK may be wedged mid-`next()`
// (interrupt() is not guaranteed to make it yield). Killing the
// process is the one reliable way out: the next turn simply
// pays a cold start rather than inheriting a broken session.
diff --git a/apps/server/src/services/llm/providers/claude_session_pool.ts b/apps/server/src/services/llm/providers/claude_session_pool.ts
index 4f511dad02..70f3c573b1 100644
--- a/apps/server/src/services/llm/providers/claude_session_pool.ts
+++ b/apps/server/src/services/llm/providers/claude_session_pool.ts
@@ -177,16 +177,16 @@ export function closeSession(chatNoteId: string, session: ClaudeSession): void {
}
}
+/** Close the least recently used idle sessions until the pool is within {@link MAX_WARM_SESSIONS}. */
function evictOldest(): void {
- while (sessionsByChatNote.size > MAX_WARM_SESSIONS) {
- const [oldestId, oldest] = [...sessionsByChatNote.entries()][0];
- // Never evict a session mid-turn; stop at the first busy one so a
- // pathological all-busy map degrades to "no eviction" instead of
- // killing a live reply.
- if (oldest.busy) {
+ for (const [chatNoteId, session] of [...sessionsByChatNote.entries()]) {
+ if (sessionsByChatNote.size <= MAX_WARM_SESSIONS) {
break;
}
- closeSession(oldestId, oldest);
+ // A busy session is streaming a reply, so it is skipped rather than closed.
+ if (!session.busy) {
+ closeSession(chatNoteId, session);
+ }
}
}
diff --git a/apps/server/src/services/llm/providers/copilot_agent.spec.ts b/apps/server/src/services/llm/providers/copilot_agent.spec.ts
index fcf81a4756..aaf589a28a 100644
--- a/apps/server/src/services/llm/providers/copilot_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/copilot_agent.spec.ts
@@ -52,6 +52,9 @@ class FakeAcpClient {
static current: FakeAcpClient | undefined;
static promptScript: (client: FakeAcpClient) => Promise<{ stopReason?: string }> = async () => ({ stopReason: "end_turn" });
static initializeError: Error | undefined;
+ /** What `initialize` answers with. */
+ static initializeResult: unknown = {};
+ static sessionCloseError: Error | undefined;
static sessionNewError: Error | undefined;
static sessionLoadError: Error | undefined;
static setModelError: Error | undefined;
@@ -79,7 +82,7 @@ class FakeAcpClient {
this.requests.push({ method, params });
if (method === "initialize") {
if (FakeAcpClient.initializeError) throw FakeAcpClient.initializeError;
- return {} as T;
+ return FakeAcpClient.initializeResult as T;
}
if (method === "session/new") {
if (FakeAcpClient.sessionNewError) throw FakeAcpClient.sessionNewError;
@@ -96,6 +99,7 @@ class FakeAcpClient {
return {} as T;
}
if (method === "session/prompt") return (await FakeAcpClient.promptScript(this)) as T;
+ if (method === "session/close" && FakeAcpClient.sessionCloseError) throw FakeAcpClient.sessionCloseError;
return {} as T;
}
@@ -166,6 +170,8 @@ function resetFakes() {
FakeAcpClient.sessionModels = undefined;
FakeAcpClient.current = undefined;
FakeAcpClient.initializeError = undefined;
+ FakeAcpClient.initializeResult = {};
+ FakeAcpClient.sessionCloseError = undefined;
FakeAcpClient.sessionNewError = undefined;
FakeAcpClient.sessionLoadError = undefined;
FakeAcpClient.setModelError = undefined;
@@ -601,15 +607,18 @@ describe("CopilotAgentProvider.chatChunks", () => {
it("reseeds a fresh session when session/load fails", async () => {
const provider = new CopilotAgentProvider();
- await collect(provider.chatChunks([userMessage("hi")], { chatNoteId: "chat-load-fail" }));
+ await collect(provider.chatChunks([userMessage("hi")], { chatNoteId: "chat-load-fail", enableNoteTools: true }));
FakeAcpClient.current?.die();
FakeAcpClient.sessionLoadError = new Error("unknown session");
FakeAcpClient.newSessionId = "sess-2";
+ mcpEndpointMock.mockClear();
const chunks = await collect(provider.chatChunks(
[userMessage("hi"), assistantMessage(""), userMessage("more")],
- { chatNoteId: "chat-load-fail" }
+ { chatNoteId: "chat-load-fail", enableNoteTools: true }
));
+ // The failed load and the new session share one MCP server list.
+ expect(mcpEndpointMock).toHaveBeenCalledTimes(1);
expect(FakeAcpClient.current?.requests.map(r => r.method))
.toEqual(["initialize", "session/load", "session/new", "session/prompt"]);
@@ -846,6 +855,27 @@ describe("CopilotAgentProvider.generateTitle", () => {
expect(FakeAcpClient.current?.disposed).toBe(false);
});
+ it("closes the title session when the agent supports session/close", async () => {
+ const provider = new CopilotAgentProvider();
+ await provider.generateTitle("hi");
+ expect(FakeAcpClient.current?.requests.some(r => r.method === "session/close")).toBe(false);
+
+ resetModelCatalogCacheForTests();
+ FakeAcpClient.initializeResult = { agentCapabilities: { sessionCapabilities: { close: {} } } };
+ FakeAcpClient.newSessionId = "sess-title";
+ await provider.generateTitle("hi");
+ expect(FakeAcpClient.current?.requests.at(-1)).toEqual({ method: "session/close", params: { sessionId: "sess-title" } });
+
+ // A refused close leaves the title intact.
+ FakeAcpClient.sessionCloseError = new Error("unknown session");
+ FakeAcpClient.promptScript = async client => {
+ client.update({ sessionUpdate: "agent_message_chunk", content: { type: "text", text: "Kept" } }, "sess-title");
+ return { stopReason: "end_turn" };
+ };
+ expect(await provider.generateTitle("hi")).toBe("Kept");
+ expect(infoLogMock).toHaveBeenCalledWith(expect.stringContaining("session/close failed (unknown session)"));
+ });
+
it("still produces a title when the cheap model cannot be selected", async () => {
FakeAcpClient.setModelError = new Error("model unavailable");
FakeAcpClient.promptScript = async client => {