Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
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.tsnew file mode 100644index 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.tsindex 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 implresolveAttachmentPartMock.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.tsindex 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[]): AsyncIteryield { 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.tsnew file mode 100644index 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();+}