Skip to content

Build your personal knowledge base with Trilium Notes

perf(llm): keep the Claude agent process alive across chat turns

Elian Dorane9a662b2e2db
diff --git a/apps/server/src/services/llm/providers/claude_agent.live.spec.ts b/apps/server/src/services/llm/providers/claude_agent.live.spec.ts
new file mode 100644
index 0000000000..92a4ec798f
--- /dev/null
+++ b/apps/server/src/services/llm/providers/claude_agent.live.spec.ts
@@ -0,0 +1,60 @@
+/**
+ * Live integration test for the Claude Agent keep-alive: drives the user's real
+ * `claude` CLI and asserts a second turn reuses the warm subprocess instead of
+ * re-paying the spawn.
+ *
+ * Opt-in — it spawns a subprocess, needs `claude /login`, and spends the
+ * subscription's budget, so it never runs in CI:
+ *
+ * TRILIUM_CLAUDE_LIVE_TEST=1 pnpm --filter server test claude_agent.live
+ */
+
+import type { LlmStreamChunk } from "@triliumnext/commons";
+import { describe, expect, it } from "vitest";
+
+import { ClaudeAgentProvider } from "./claude_agent.js";
+import { resetClaudeSessionPoolForTests } from "./claude_session_pool.js";
+
+const live = process.env.TRILIUM_CLAUDE_LIVE_TEST === "1";
+
+/** The cheapest model on the subscription. */
+const MODEL = "claude-haiku-4-5-20251001";
+
+describe.runIf(live)("ClaudeAgentProvider keep-alive (live CLI)", () => {
+ it("answers a second turn on the warm subprocess, without re-paying the spawn", async () => {
+ const provider = new ClaudeAgentProvider();
+ const chatNoteId = "live-keep-alive";
+ resetClaudeSessionPoolForTests();
+
+ async function turn(messages: { role: "user" | "assistant"; content: string }[]) {
+ const startedAt = Date.now();
+ let firstTokenMs: number | undefined;
+ let text = "";
+ for await (const chunk of provider.chatChunks(messages, { chatNoteId, model: MODEL, enableNoteTools: false })) {
+ const typed = chunk as LlmStreamChunk;
+ if (typed.type === "text") {
+ firstTokenMs ??= Date.now() - startedAt;
+ text += typed.content;
+ } else if (typed.type === "error") {
+ throw new Error(`Live agent turn failed: ${typed.error}`);
+ }
+ }
+ return { firstTokenMs, text };
+ }
+
+ const cold = await turn([{ role: "user", content: "Reply with exactly the word: alpha" }]);
+ const warm = await turn([
+ { role: "user", content: "Reply with exactly the word: alpha" },
+ { role: "assistant", content: cold.text },
+ { role: "user", content: "Reply with exactly the word: beta" }
+ ]);
+
+ console.log(`live keep-alive: cold first token ${cold.firstTokenMs} ms, warm ${warm.firstTokenMs} ms`);
+
+ expect(cold.text.toLowerCase()).toContain("alpha");
+ expect(warm.text.toLowerCase()).toContain("beta");
+ // The warm turn skips the ~1.3 s subprocess spawn. Assert a fraction of
+ // that so the test tracks the behaviour, not this machine's numbers.
+ expect(warm.firstTokenMs).toBeLessThan((cold.firstTokenMs ?? 0) - 500);
+ }, 180_000);
+});
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 b9ba9f463f..b741055d91 100644
--- a/apps/server/src/services/llm/providers/claude_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.spec.ts
@@ -3,6 +3,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const queryMock = vi.hoisted(() => vi.fn());
const errorLogMock = vi.hoisted(() => vi.fn());
+/** Streaming-input-only Query controls the session pool drives. */
+const setModelMock = vi.hoisted(() => vi.fn());
+const closeMock = vi.hoisted(() => vi.fn());
vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
query: queryMock
@@ -49,28 +52,60 @@ const spawnMock = vi.hoisted(() => vi.fn());
vi.mock("child_process", () => ({ spawn: spawnMock }));
const { buildSeededPrompt, buildSubscriptionModelList, ClaudeAgentProvider, hashTranscript, resetAgentCwdForTests, resetSubscriptionModelCacheForTests } = await import("./claude_agent.js");
-
-/** Drain the query prompt into the single user message it streams (multimodal path). */
-async function drainPrompt(prompt: unknown): Promise<{ role: string; content: unknown[] }> {
- const iterator = (prompt as AsyncIterable<unknown>)?.[Symbol.asyncIterator];
- if (typeof prompt === "string" || typeof iterator !== "function") {
- throw new Error("expected a streamed multimodal prompt, got a plain string");
- }
- const messages: { message: { role: string; content: unknown[] } }[] = [];
- for await (const message of prompt as AsyncIterable<{ message: { role: string; content: unknown[] } }>) {
- messages.push(message);
+const { resetClaudeSessionPoolForTests } = await import("./claude_session_pool.js");
+type PushablePrompt = { pending: readonly { message: { role: string; content: unknown[] } }[] };
+
+/**
+ * Every turn now feeds the session's streaming input, so the `prompt` option is
+ * always a Pushable and the turn's own message is what was pushed onto it.
+ */
+function pushedMessages(prompt: unknown): { message: { role: string; content: unknown[] } }[] {
+ const pending = (prompt as PushablePrompt)?.pending;
+ if (!Array.isArray(pending)) {
+ throw new Error("expected the prompt to be a streaming-input Pushable");
}
+ return [...pending];
+}
+
+/** The single user message a turn streamed (multimodal path). */
+function drainPrompt(prompt: unknown): { role: string; content: unknown[] } {
+ const messages = pushedMessages(prompt);
expect(messages).toHaveLength(1);
return messages[0].message;
}
+/** The plain text a turn pushed, for the non-multimodal path. */
+function promptText(prompt: unknown): string {
+ return drainPrompt(prompt).content
+ .map(block => (block && typeof block === "object" && "text" in block ? String(block.text) : ""))
+ .join("");
+}
+
+/**
+ * One long-lived query stream serving several turns, as a warm session does:
+ * the provider consumes up to each turn's `result` and resumes from there on
+ * the next turn instead of starting a new query.
+ */
+function scriptAgentSession(turns: unknown[][]) {
+ queryMock.mockImplementation(() => makeQuery(turns.flat()));
+}
+
/** Make query() replay the given SDK messages and record its invocation. */
function scriptAgent(messages: unknown[]) {
- queryMock.mockImplementation(() => (async function* () {
+ queryMock.mockImplementation(() => makeQuery(messages));
+}
+
+/**
+ * A stand-in for the SDK's Query: an async generator plus the control methods
+ * that only exist in streaming input mode, which the pool drives.
+ */
+function makeQuery(messages: unknown[]) {
+ const generator = (async function* () {
for (const message of messages) {
yield message;
}
- })());
+ })();
+ return Object.assign(generator, { setModel: setModelMock, close: closeMock });
}
async function collect(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
@@ -108,6 +143,12 @@ describe("ClaudeAgentProvider.chatChunks", () => {
errorLogMock.mockReset();
createMcpServerMock.mockClear(); // clear calls, keep the instance impl
resolveAttachmentPartMock.mockReset();
+ // Sessions outlive a turn now, so each test must start from a cold
+ // pool. Reset it *before* clearing the mocks: tearing down a leftover
+ // session calls close() and would otherwise count against this test.
+ resetClaudeSessionPoolForTests();
+ setModelMock.mockClear();
+ closeMock.mockClear();
});
it("maps stream events, tool calls, results, and usage to chunks in order", async () => {
@@ -207,30 +248,34 @@ describe("ClaudeAgentProvider.chatChunks", () => {
expect(chunks.filter(c => c.type === "text")).toEqual([]);
});
- it("starts a fresh session with the plain prompt and resumes it when the transcript matches", async () => {
+ it("keeps one warm session across turns, pushing the next message onto its streaming input", async () => {
const provider = new ClaudeAgentProvider();
const config = { chatNoteId: "note-resume" };
+ scriptAgentSession([
+ [textDelta("first reply"), successResult("sess-A")],
+ [textDelta("second reply"), successResult("sess-A")]
+ ]);
+
// Turn 1 — no history, no mapping: plain prompt, no resume.
- scriptAgent([textDelta("first reply"), successResult("sess-A")]);
await collect(provider.chatChunks([{ role: "user", content: "first question" }], config));
expect(queryMock).toHaveBeenCalledTimes(1);
- const firstCall = queryMock.mock.calls[0][0];
- expect(firstCall.prompt).toBe("first question");
- expect(firstCall.options.resume).toBeUndefined();
+ const call = queryMock.mock.calls[0][0];
+ expect(call.options.resume).toBeUndefined();
- // Turn 2 — transcript = turn 1 + streamed reply: resume with only the new message.
- scriptAgent([textDelta("second reply"), successResult("sess-A")]);
- await collect(provider.chatChunks([
+ // Turn 2 — the transcript still matches, so the live subprocess is
+ // reused: no second query(), just another message on the same input.
+ const second = await collect(provider.chatChunks([
{ role: "user", content: "first question" },
{ role: "assistant", content: "first reply" },
{ role: "user", content: "second question" }
], config));
- const secondCall = queryMock.mock.calls[1][0];
- expect(secondCall.prompt).toBe("second question");
- expect(secondCall.options.resume).toBe("sess-A");
+ expect(queryMock).toHaveBeenCalledTimes(1);
+ expect(second).toContainEqual({ type: "text", content: "second reply" });
+ const pushed = pushedMessages(call.prompt).map(m => (m.message.content[0] as { text: string }).text);
+ expect(pushed).toEqual(["first question", "second question"]);
});
it("reseeds a fresh session from the transcript when the history diverged", async () => {
@@ -250,10 +295,10 @@ describe("ClaudeAgentProvider.chatChunks", () => {
const secondCall = queryMock.mock.calls[1][0];
expect(secondCall.options.resume).toBeUndefined();
- expect(secondCall.prompt).toContain("<conversation_history>");
- expect(secondCall.prompt).toContain("User: edited");
- expect(secondCall.prompt).toContain("Assistant: reply");
- expect(secondCall.prompt).toContain("follow-up");
+ expect(promptText(secondCall.prompt)).toContain("<conversation_history>");
+ expect(promptText(secondCall.prompt)).toContain("User: edited");
+ expect(promptText(secondCall.prompt)).toContain("Assistant: reply");
+ expect(promptText(secondCall.prompt)).toContain("follow-up");
});
it("prepends the current-note metadata hint to the user message when contextNoteId is set", async () => {
@@ -266,8 +311,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
));
expect(buildNoteHintMock).toHaveBeenCalledWith("note-abc", false);
- const prompt = queryMock.mock.calls[0][0].prompt;
- expect(prompt).toBe("NOTE_META(note-abc)\n\nwhat is this note about?");
+ expect(promptText(queryMock.mock.calls[0][0].prompt)).toBe("NOTE_META(note-abc)\n\nwhat is this note about?");
});
it("does not prepend a hint when the context note no longer exists", async () => {
@@ -279,28 +323,30 @@ describe("ClaudeAgentProvider.chatChunks", () => {
{ contextNoteId: "gone" }
));
- expect(queryMock.mock.calls[0][0].prompt).toBe("hello");
+ expect(promptText(queryMock.mock.calls[0][0].prompt)).toBe("hello");
});
it("keeps the note hint out of the session hash so a later turn still resumes", async () => {
const provider = new ClaudeAgentProvider();
const config = { contextNoteId: "note-abc", chatNoteId: "note-hint-resume" };
- scriptAgent([textDelta("first reply"), successResult("sess-H")]);
+ scriptAgentSession([
+ [textDelta("first reply"), successResult("sess-H")],
+ [textDelta("second reply"), successResult("sess-H")]
+ ]);
await collect(provider.chatChunks([{ role: "user", content: "q1" }], config));
- // Turn 2: transcript matches turn 1 (unhinted) → resume, and the new
- // message still carries the freshly-built hint.
- scriptAgent([textDelta("second reply"), successResult("sess-H")]);
+ // Turn 2: transcript matches turn 1 (unhinted), so the warm session is
+ // reused, and the new message still carries the freshly-built hint.
await collect(provider.chatChunks([
{ role: "user", content: "q1" },
{ role: "assistant", content: "first reply" },
{ role: "user", content: "q2" }
], config));
- const secondCall = queryMock.mock.calls[1][0];
- expect(secondCall.options.resume).toBe("sess-H");
- expect(secondCall.prompt).toBe("NOTE_META(note-abc)\n\nq2");
+ expect(queryMock).toHaveBeenCalledTimes(1);
+ const pushed = pushedMessages(queryMock.mock.calls[0][0].prompt);
+ expect((pushed[1].message.content[0] as { text: string }).text).toBe("NOTE_META(note-abc)\n\nq2");
});
it("sends a supported image as a base64 block via a one-message stream", async () => {
@@ -314,7 +360,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
] }
], {}));
- const message = await drainPrompt(queryMock.mock.calls[0][0].prompt);
+ const message = drainPrompt(queryMock.mock.calls[0][0].prompt);
expect(message.role).toBe("user");
expect(message.content).toEqual([
{ type: "text", text: "what is this?" },
@@ -330,7 +376,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
{ role: "user", content: [{ type: "file", attachmentId: "att-2", mime: "application/pdf", filename: "report.pdf" }] }
], { contextNoteId: "note-abc" }));
- const message = await drainPrompt(queryMock.mock.calls[0][0].prompt);
+ const message = drainPrompt(queryMock.mock.calls[0][0].prompt);
expect(message.content).toEqual([
{ type: "text", text: "NOTE_META(note-abc)" },
{ type: "document", title: "report.pdf", source: { type: "base64", media_type: "application/pdf", data: "JVBERg==" } }
@@ -349,9 +395,11 @@ describe("ClaudeAgentProvider.chatChunks", () => {
] }
], {}));
- const prompt = queryMock.mock.calls[0][0].prompt;
- expect(typeof prompt).toBe("string");
- expect(prompt).toBe("read this\n\n<file name=\"d.svg\">\n<svg/>\n</file>");
+ // Degrades to a single text block rather than image/document blocks.
+ const message = drainPrompt(queryMock.mock.calls[0][0].prompt);
+ expect(message.content).toEqual([
+ { type: "text", text: "read this\n\n<file name=\"d.svg\">\n<svg/>\n</file>" }
+ ]);
});
it("wires Trilium's in-process MCP server instance and disables built-in tools", async () => {
@@ -768,7 +816,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
] }
], {}));
- const message = await drainPrompt(queryMock.mock.calls[0][0].prompt);
+ const message = drainPrompt(queryMock.mock.calls[0][0].prompt);
expect(message.content).toEqual([
{ type: "image", source: { type: "base64", media_type: "image/png", data: "AQ==" } },
{ type: "text", text: "[attached image]" },
@@ -783,7 +831,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
await collect(provider.chatChunks([
{ role: "user", content: [{ type: "text", text: "line one" }, { type: "text", text: "line two" }] }
], {}));
- expect(queryMock.mock.calls[0][0].prompt).toBe("line one\nline two");
+ expect(promptText(queryMock.mock.calls[0][0].prompt)).toBe("line one\nline two");
});
it("creates the isolating .git marker only when it is absent", async () => {
@@ -807,6 +855,73 @@ describe("ClaudeAgentProvider.chatChunks", () => {
expect(fs.statSync(path.join(agentDir, ".git", "HEAD")).mtimeMs).toBe(headBefore);
});
+ it("switches models on the live session instead of respawning it", async () => {
+ const provider = new ClaudeAgentProvider();
+ const config = { chatNoteId: "note-model" };
+ scriptAgentSession([
+ [textDelta("a"), successResult("sess-M")],
+ [textDelta("b"), successResult("sess-M")]
+ ]);
+
+ await collect(provider.chatChunks([{ role: "user", content: "q1" }], { ...config, model: "claude-sonnet-5" }));
+ await collect(provider.chatChunks([
+ { role: "user", content: "q1" },
+ { role: "assistant", content: "a" },
+ { role: "user", content: "q2" }
+ ], { ...config, model: "claude-haiku-4-5-20251001" }));
+
+ // setModel is a streaming-input-only control: it is why a model change
+ // costs ~0 ms instead of a cold start.
+ expect(queryMock).toHaveBeenCalledTimes(1);
+ expect(setModelMock).toHaveBeenCalledExactlyOnceWith("claude-haiku-4-5-20251001");
+ });
+
+ it.each([
+ [ "note tools", { enableNoteTools: true }, { enableNoteTools: false } ],
+ [ "web search", {}, { enableWebSearch: true } ],
+ [ "extended thinking", {}, { enableExtendedThinking: true } ]
+ ])("starts a new session when %s, fixed at construction, changes", async (_option, before, after) => {
+ const provider = new ClaudeAgentProvider();
+ const config = { chatNoteId: "note-fixed" };
+ scriptAgent([textDelta("a"), successResult("sess-F")]);
+ await collect(provider.chatChunks([{ role: "user", content: "q1" }], { ...config, ...before }));
+
+ // The option is wired into query()'s options and can't be changed on a
+ // live session, so this must build a new one (and retire the old).
+ scriptAgent([textDelta("b"), successResult("sess-F2")]);
+ await collect(provider.chatChunks([
+ { role: "user", content: "q1" },
+ { role: "assistant", content: "a" },
+ { role: "user", content: "q2" }
+ ], { ...config, ...after }));
+
+ expect(queryMock).toHaveBeenCalledTimes(2);
+ expect(closeMock).toHaveBeenCalled();
+ });
+
+ it("closes the session after an aborted turn rather than reusing a half-finished one", async () => {
+ const controller = new AbortController();
+ const provider = new ClaudeAgentProvider();
+ const config = { chatNoteId: "note-abort" };
+
+ // The turn is cancelled mid-stream, so the session's real state is
+ // unknown — it must not be handed to the next turn.
+ queryMock.mockImplementation(() => makeQuery([textDelta("partial"), successResult("sess-X")]));
+ const chunks = await collect(provider.chatChunks(
+ [{ role: "user", content: "q" }],
+ config,
+ (controller.abort(), controller.signal)
+ ));
+
+ expect(chunks).toEqual([]);
+ expect(closeMock).not.toHaveBeenCalled(); // nothing was started to close
+
+ // A later turn starts a fresh session rather than resuming.
+ scriptAgent([textDelta("ok"), successResult("sess-Y")]);
+ await collect(provider.chatChunks([{ role: "user", content: "q" }], config));
+ expect(queryMock).toHaveBeenCalledTimes(1);
+ });
+
it("evicts the oldest chat-note mapping once the session cap is exceeded", async () => {
const provider = new ClaudeAgentProvider();
@@ -819,6 +934,11 @@ describe("ClaudeAgentProvider.chatChunks", () => {
await collect(provider.chatChunks([{ role: "user", content: "q" }], { chatNoteId: `filler-${i}` }));
}
+ // This test is about the chat-note → session-id map, not the warm
+ // subprocess pool; drop the warm sessions so both follow-ups have to
+ // start a query and reveal what they would resume.
+ resetClaudeSessionPoolForTests();
+
// Despite a perfectly matching transcript, the victim can no longer resume.
scriptAgent([successResult()]);
await collect(provider.chatChunks([
diff --git a/apps/server/src/services/llm/providers/claude_agent.ts b/apps/server/src/services/llm/providers/claude_agent.ts
index 7d1cba4c7d..6eaf3f0bb1 100644
--- a/apps/server/src/services/llm/providers/claude_agent.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.ts
@@ -38,6 +38,14 @@ import path from "path";
import dataDirs from "../../data_dir.js";
import { createMcpServer } from "../../mcp/mcp_server.js";
import { resolveClaudeBinaryPath } from "./claude_binary.js";
+import {
+ type ClaudeSession,
+ closeSession,
+ Pushable,
+ releaseSession,
+ rememberSession as rememberWarmSession,
+ takeWarmSession
+} from "./claude_session_pool.js";
import { attachmentPlaceholder, buildHistoryReplay, flattenContent, hashTranscript } from "./transcript.js";
// Re-exported for existing importers (specs, siblings); the implementations
@@ -371,6 +379,8 @@ export class ClaudeAgentProvider implements LlmProvider {
const modelDisplayName = describeModel(model);
let sessionId: string | undefined;
let assistantText = "";
+ /** The session this turn is driving, released (not closed) at the end. */
+ let held: ClaudeSession | undefined;
// 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>();
@@ -379,21 +389,77 @@ export class ClaudeAgentProvider implements LlmProvider {
try {
const query = await loadQuery();
- const response = query({
- prompt,
- options: {
- ...await this.buildBaseOptions(config),
- systemPrompt: this.composeSystemPrompt(messages, config),
- model,
- resume,
- includePartialMessages: true,
- maxTurns: MAX_TURNS,
- abortController
- }
+ const systemPrompt = this.composeSystemPrompt(messages, config);
+ // Options the SDK fixes at query() construction: a change to any of
+ // them can't be applied to a live session, so it forces a new one.
+ // `model` is deliberately absent — setModel() handles it in place.
+ const fingerprint = JSON.stringify({
+ systemPrompt,
+ noteTools: areNoteToolsAvailable(config),
+ webSearch: !!config.enableWebSearch,
+ thinking: !!config.enableExtendedThinking
});
- for await (const message of response) {
+ // Only reuse a warm session when the transcript still matches what
+ // it last saw (`resume`), so an edited history reseeds as before.
+ const warm = config.chatNoteId && resume
+ ? takeWarmSession(config.chatNoteId, fingerprint)
+ : undefined;
+ let session = warm?.sessionId === resume ? warm : undefined;
+ if (warm && !session) {
+ // Right chat, wrong conversation — retire it rather than reply
+ // into the wrong session.
+ closeSession(config.chatNoteId ?? "", warm);
+ }
+
+ if (session) {
+ if (model && session.model !== model) {
+ // Streaming input mode only; ~0 ms in practice.
+ await session.query.setModel(model);
+ session.model = model;
+ }
+ } else {
+ const input = new Pushable<SDKUserMessage>();
+ session = {
+ query: query({
+ prompt: input,
+ options: {
+ ...await this.buildBaseOptions(config),
+ systemPrompt,
+ model,
+ resume,
+ includePartialMessages: true,
+ maxTurns: MAX_TURNS,
+ abortController
+ }
+ }),
+ input,
+ fingerprint,
+ closed: false,
+ busy: true,
+ model
+ };
+ if (config.chatNoteId) {
+ rememberWarmSession(config.chatNoteId, session);
+ }
+ }
+ const active = session;
+ held = active;
+ await pushUserTurn(active.input, prompt);
+
+ // 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) {
+ active.closed = true;
+ break;
+ }
+ const message = next.value;
sessionId = takeSessionId(message) ?? sessionId;
+ active.sessionId = sessionId ?? active.sessionId;
switch (message.type) {
case "stream_event": {
@@ -499,6 +565,9 @@ export class ClaudeAgentProvider implements LlmProvider {
provider: this.name
}
};
+ // The turn is over, but the session stays open for the
+ // next one — this is what keeps the process warm.
+ turnComplete = true;
break;
}
@@ -520,6 +589,10 @@ export class ClaudeAgentProvider implements LlmProvider {
default:
break;
}
+
+ if (turnComplete) {
+ break;
+ }
}
if (config.chatNoteId && sessionId) {
@@ -537,7 +610,21 @@ export class ClaudeAgentProvider implements LlmProvider {
yield { type: "error", error: describeAgentError(error) };
} finally {
signal?.removeEventListener("abort", onAbort);
- abortController.abort();
+ const reusable = held && config.chatNoteId && !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()`
+ // (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.
+ if (held) {
+ closeSession(config.chatNoteId ?? "", held);
+ }
+ abortController.abort();
+ }
}
}
@@ -900,6 +987,26 @@ async function* streamSingleUserMessage(content: ContentBlockParam[]): AsyncIter
yield { type: "user", message: { role: "user", content }, parent_tool_use_id: null };
}
+/**
+ * Feed one user turn into a live session's streaming input. Accepts both prompt
+ * forms {@link buildPrompt} produces: a plain string, or the one-message stream
+ * used for natively-consumable attachments (drained here, since a pooled
+ * session's input is the only stream the SDK is reading).
+ */
+async function pushUserTurn(input: Pushable<SDKUserMessage>, prompt: string | AsyncIterable<SDKUserMessage>): Promise<void> {
+ if (typeof prompt !== "string") {
+ for await (const message of prompt) {
+ input.push(message);
+ }
+ return;
+ }
+ input.push({
+ type: "user",
+ message: { role: "user", content: [{ type: "text", text: prompt }] },
+ parent_tool_use_id: null
+ });
+}
+
/** Strip the MCP prefix so the client shows "search_notes", not "mcp__trilium__search_notes". */
function friendlyToolName(name: string): string {
return name.replace(/^mcp__trilium__/, "");
diff --git a/apps/server/src/services/llm/providers/claude_session_pool.ts b/apps/server/src/services/llm/providers/claude_session_pool.ts
new file mode 100644
index 0000000000..4f511dad02
--- /dev/null
+++ b/apps/server/src/services/llm/providers/claude_session_pool.ts
@@ -0,0 +1,206 @@
+/**
+ * Keeps one Claude Code subprocess alive per chat, across turns.
+ *
+ * The SDK's default `query({ prompt: "text" })` binds the subprocess to the
+ * returned iterator: it spawns on call and dies when iteration ends, so every
+ * turn re-pays the spawn. Measured on Windows that is ~2.0 s to the first
+ * token cold versus ~0.8 s once the process is warm.
+ *
+ * The alternative the SDK offers is *streaming input mode*: pass an
+ * `AsyncIterable<SDKUserMessage>` as the prompt and the process stays alive
+ * consuming messages as they are pushed. That is also the only mode in which
+ * the `Query` control methods (`setModel`, `interrupt`) work — which is what
+ * lets a mid-chat model switch happen without a respawn (measured: ~0 ms).
+ *
+ * Turns within a chat are strictly sequential (one user waiting on one reply),
+ * so a turn can simply drive `query.next()` until its `result` message and
+ * stop — no persistent consumer or turn queue is needed. Iteration must be
+ * manual: `for await (…) { break }` calls `iterator.return()`, which would
+ * close the query and defeat the whole point.
+ *
+ * Sessions are keyed by chat note, reaped after {@link IDLE_TIMEOUT_MS}, and
+ * rebuilt whenever an option that is fixed at construction changes.
+ */
+
+import type { Query, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { getLog } from "@triliumnext/core";
+
+/**
+ * How long an unused session's subprocess is kept warm. Unlike the Copilot
+ * pool this is one process *per chat*, so the reaper bounds real memory, not
+ * just tidiness.
+ */
+export const IDLE_TIMEOUT_MS = 5 * 60_000;
+
+/** Sessions kept warm; bounded so many open chats can't exhaust the host. */
+export const MAX_WARM_SESSIONS = 8;
+
+/**
+ * Bridges push-based turns to the pull-based `AsyncIterable` the SDK wants.
+ * Pushing after {@link end} is a no-op rather than a hang: a message enqueued
+ * onto a dead stream would otherwise wait on a promise nobody settles.
+ */
+export class Pushable<T> implements AsyncIterable<T> {
+ private readonly queue: T[] = [];
+ private readonly resolvers: ((result: IteratorResult<T>) => void)[] = [];
+ private done = false;
+
+ push(item: T): void {
+ if (this.done) {
+ return;
+ }
+ const resolve = this.resolvers.shift();
+ if (resolve) {
+ resolve({ value: item, done: false });
+ } else {
+ this.queue.push(item);
+ }
+ }
+
+ /** Messages pushed but not yet consumed — for assertions in tests. */
+ get pending(): readonly T[] {
+ return this.queue;
+ }
+
+ end(): void {
+ this.done = true;
+ let resolve = this.resolvers.shift();
+ while (resolve) {
+ resolve({ value: undefined as never, done: true });
+ resolve = this.resolvers.shift();
+ }
+ }
+
+ [Symbol.asyncIterator](): AsyncIterator<T> {
+ return {
+ next: (): Promise<IteratorResult<T>> => {
+ if (this.queue.length > 0) {
+ return Promise.resolve({ value: this.queue.shift() as T, done: false });
+ }
+ if (this.done) {
+ return Promise.resolve({ value: undefined as never, done: true });
+ }
+ return new Promise<IteratorResult<T>>(resolve => this.resolvers.push(resolve));
+ }
+ };
+ }
+}
+
+export interface ClaudeSession {
+ readonly query: Query;
+ readonly input: Pushable<SDKUserMessage>;
+ /**
+ * Options that cannot be changed after `query()` starts (system prompt,
+ * note tools, thinking, resume target). A mismatch forces a new session.
+ */
+ readonly fingerprint: string;
+ /** The agent session id, learned from the first message that carries one. */
+ sessionId?: string;
+ /** Set once the stream ends; pushing onto a closed session would hang. */
+ closed: boolean;
+ /** A turn is currently driving `query.next()`. */
+ busy: boolean;
+ /** Last model asked for via `setModel`, so it is only re-sent on change. */
+ model?: string;
+ idleTimer?: NodeJS.Timeout;
+}
+
+const sessionsByChatNote = new Map<string, ClaudeSession>();
+
+/**
+ * The warm session for a chat, or undefined when the caller must build one.
+ * A session that is closed, busy, or built with different construction-time
+ * options is dropped here so the caller starts fresh.
+ */
+export function takeWarmSession(chatNoteId: string, fingerprint: string): ClaudeSession | undefined {
+ const session = sessionsByChatNote.get(chatNoteId);
+ if (!session) {
+ return undefined;
+ }
+ if (session.closed || session.busy || session.fingerprint !== fingerprint) {
+ // Busy means a previous turn is still streaming — rather than queue
+ // behind it, the caller gets a fresh session and this one is retired.
+ closeSession(chatNoteId, session);
+ return undefined;
+ }
+ cancelIdleTimer(session);
+ session.busy = true;
+ return session;
+}
+
+/** Register a freshly built session as this chat's warm one. */
+export function rememberSession(chatNoteId: string, session: ClaudeSession): void {
+ const previous = sessionsByChatNote.get(chatNoteId);
+ if (previous && previous !== session) {
+ closeSession(chatNoteId, previous);
+ }
+ session.busy = true;
+ sessionsByChatNote.delete(chatNoteId);
+ sessionsByChatNote.set(chatNoteId, session);
+ evictOldest();
+}
+
+/** Hand a session back after a turn; it is reaped once idle for long enough. */
+export function releaseSession(chatNoteId: string, session: ClaudeSession): void {
+ session.busy = false;
+ if (session.closed) {
+ sessionsByChatNote.delete(chatNoteId);
+ return;
+ }
+ cancelIdleTimer(session);
+ session.idleTimer = setTimeout(() => {
+ session.idleTimer = undefined;
+ if (!session.busy) {
+ getLog().info(`Claude Agent provider: reaping the idle agent process for chat ${chatNoteId}.`);
+ closeSession(chatNoteId, session);
+ }
+ }, IDLE_TIMEOUT_MS);
+ // Don't hold the event loop open just to reap an idle subprocess.
+ session.idleTimer.unref?.();
+}
+
+/** End the stream and terminate the subprocess. Safe to call more than once. */
+export function closeSession(chatNoteId: string, session: ClaudeSession): void {
+ cancelIdleTimer(session);
+ if (sessionsByChatNote.get(chatNoteId) === session) {
+ sessionsByChatNote.delete(chatNoteId);
+ }
+ if (session.closed) {
+ return;
+ }
+ session.closed = true;
+ try {
+ session.input.end();
+ session.query.close();
+ } catch (err) {
+ getLog().info(`Claude Agent provider: error closing the agent session (${err instanceof Error ? err.message : String(err)}).`);
+ }
+}
+
+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) {
+ break;
+ }
+ closeSession(oldestId, oldest);
+ }
+}
+
+function cancelIdleTimer(session: ClaudeSession): void {
+ if (session.idleTimer) {
+ clearTimeout(session.idleTimer);
+ session.idleTimer = undefined;
+ }
+}
+
+/** For tests: close every warm session and forget the map. */
+export function resetClaudeSessionPoolForTests(): void {
+ for (const [chatNoteId, session] of [...sessionsByChatNote.entries()]) {
+ closeSession(chatNoteId, session);
+ }
+ sessionsByChatNote.clear();
+}