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
feat(llm): empty the Claude Code title session with /clear
Elian Doran4e7abe978c83
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.tsindex 92a4ec798f..45b76b87f4 100644--- a/apps/server/src/services/llm/providers/claude_agent.live.spec.ts+++ b/apps/server/src/services/llm/providers/claude_agent.live.spec.ts@@ -1,7 +1,7 @@/**- * 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.+ * Live integration tests for the Claude Agent keep-alive: drive the user's real+ * `claude` CLI and assert that a second chat turn, and a later chat title, reuse+ * 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:@@ -58,3 +58,47 @@ describe.runIf(live)("ClaudeAgentProvider keep-alive (live CLI)", () => {expect(warm.firstTokenMs).toBeLessThan((cold.firstTokenMs ?? 0) - 500);}, 180_000);});++describe.runIf(live)("ClaudeAgentProvider titles (live CLI)", () => {+ it("names each chat after its own message in one warm session, emptied by /clear", async () => {+ const provider = new ClaudeAgentProvider();+ resetClaudeSessionPoolForTests();++ async function title(message: string) {+ const startedAt = Date.now();+ const text = await provider.generateTitle(message);+ return { text, ms: Date.now() - startedAt };+ }++ // Titles arrive far apart in use, so each `/clear` has finished before the next title.+ const pause = () => new Promise(resolve => setTimeout(resolve, 2000));+ const cold = await title("Give me a sourdough bread recipe with a long cold proof.");+ const warm: { text: string; ms: number }[] = [];+ for (const message of [+ "How do I change the oil on a 2015 Honda Civic?",+ "Explain how photosynthesis works in plants.",+ "Plan a week in Lisbon."+ ]) {+ await pause();+ warm.push(await title(message));+ }++ console.log(`live titles: ${JSON.stringify([cold, ...warm])}`);++ expect(cold.text.toLowerCase()).toMatch(/sourdough|bread/);+ expect(warm.map(t => t.text.toLowerCase())).toEqual([+ expect.stringMatching(/oil|civic|honda/),+ expect.stringMatching(/photosynthesis|plant|sunlight|light/),+ expect.stringMatching(/lisbon/)+ ]);+ for (const later of warm) {+ expect(later.text.toLowerCase()).not.toMatch(/sourdough|bread/);+ }+ // The model overshoots the five-word limit now and then; without the+ // examples in the system prompt it did so for about a third of titles.+ expect([cold, ...warm].filter(({ text }) => text.split(/\s+/).length > 5).length).toBeLessThanOrEqual(1);+ // A warm title skips the spawn, but the model's own latency varies by+ // about as much, so only the fastest one is held to the margin.+ expect(Math.min(...warm.map(t => t.ms))).toBeLessThan(cold.ms - 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 536f695c43..e4dfdb6fad 100644--- a/apps/server/src/services/llm/providers/claude_agent.spec.ts+++ b/apps/server/src/services/llm/providers/claude_agent.spec.ts@@ -5,6 +5,7 @@ import type { ClaudeSession } from "./claude_session_pool.js";const queryMock = vi.hoisted(() => vi.fn());const errorLogMock = vi.hoisted(() => vi.fn());+const infoLogMock = 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());@@ -14,7 +15,7 @@ vi.mock("@anthropic-ai/claude-agent-sdk", () => ({}));vi.mock("@triliumnext/core", () => ({- getLog: () => ({ info: vi.fn(), error: errorLogMock })+ getLog: () => ({ info: infoLogMock, error: errorLogMock })}));// buildSystemPrompt (reached via composeSystemPrompt) reads the workspace task@@ -56,7 +57,7 @@ vi.mock("@triliumnext/core/src/services/llm/attachment_content.js", async (imporconst spawnMock = vi.hoisted(() => vi.fn());vi.mock("child_process", () => ({ spawn: spawnMock }));-const { buildSeededPrompt, buildSubscriptionModelList, ClaudeAgentProvider, hashTranscript, resetAgentCwdForTests, resetSubscriptionModelCacheForTests } = await import("./claude_agent.js");+const { buildSeededPrompt, buildSubscriptionModelList, ClaudeAgentProvider, hashTranscript, resetAgentCwdForTests, resetSubscriptionModelCacheForTests, TITLE_TIMEOUT_MS } = await import("./claude_agent.js");const { MAX_WARM_SESSIONS, Pushable, releaseSession, rememberSession: rememberWarmSession, resetClaudeSessionPoolForTests } = await import("./claude_session_pool.js");const { buildTitlePrompt, MAX_TITLES_PER_SESSION } = await import("./transcript.js");type PushablePrompt = { pending: readonly { message: { role: string; content: unknown[] } }[] };@@ -1085,6 +1086,7 @@ describe("generateTitle", () => {beforeEach(() => {queryMock.mockReset();errorLogMock.mockReset();+ infoLogMock.mockReset();resetClaudeSessionPoolForTests();closeMock.mockClear();});@@ -1093,7 +1095,7 @@ describe("generateTitle", () => {let inFlight = 0;let maxInFlight = 0;const answered: string[] = [];- scriptTitleAgent(async prompt => {+ const pushed = scriptTitleAgent(async prompt => {inFlight++;maxInFlight = Math.max(maxInFlight, inFlight);await new Promise(resolve => setTimeout(resolve, 5));@@ -1109,6 +1111,9 @@ describe("generateTitle", () => {expect(answered).toEqual(["a", "b", "c"]);expect(maxInFlight).toBe(1);+ await vi.waitFor(() => expect(pushed).toEqual([+ buildTitlePrompt("a"), "/clear", buildTitlePrompt("b"), "/clear", buildTitlePrompt("c"), "/clear"+ ]));expect(queryMock).toHaveBeenCalledTimes(1);const options = queryMock.mock.calls[0][0].options;expect(options).toMatchObject({ model: "claude-haiku-4-5-20251001", maxTurns: 1, persistSession: false });@@ -1129,7 +1134,58 @@ describe("generateTitle", () => {expect(prompts[0]).toContain("earlier messages in this conversation do not apply");});- it("replaces the title session when it is full, failed, or its stream ended", async () => {+ it("states the five-word limit with example titles in the system prompt, since /clear leaves none in the history", async () => {+ scriptTitleAgent(async () => [titleResult("Title")]);++ await new ClaudeAgentProvider().generateTitle("hi");++ const systemPrompt: string = queryMock.mock.calls[0][0].options.systemPrompt;+ expect(systemPrompt).toContain("at most five words");+ const examples = [...systemPrompt.matchAll(/"([^"]+)"/g)].map(match => match[1]).filter(text => /^[A-Z]/.test(text) && text.includes(" "));+ expect(examples.length).toBeGreaterThanOrEqual(2);+ for (const example of examples) {+ expect(example.split(/\s+/).length).toBeLessThanOrEqual(5);+ }+ });++ it("empties the session with /clear after a title, without holding that title back", async () => {+ let releaseClear = () => {};+ const gate = new Promise<void>(resolve => {+ releaseClear = resolve;+ });+ const pushed = scriptTitleAgent(+ async prompt => [titleResult(prompt.slice(prompt.lastIndexOf("\n") + 1).toUpperCase())],+ async () => {+ await gate;+ return clearedMessages();+ }+ );+ const provider = new ClaudeAgentProvider();++ await expect(provider.generateTitle("a")).resolves.toBe("A");+ const second = provider.generateTitle("b");+ await vi.waitFor(() => expect(pushed).toEqual([buildTitlePrompt("a"), "/clear"]));++ releaseClear();+ await expect(second).resolves.toBe("B");+ expect(pushed.slice(0, 3)).toEqual([buildTitlePrompt("a"), "/clear", buildTitlePrompt("b")]);+ expect(queryMock).toHaveBeenCalledTimes(1);+ });++ it("keeps one session however many titles it answers", async () => {+ scriptTitleAgent(async () => [titleResult("Title")]);+ const provider = new ClaudeAgentProvider();++ for (let i = 0; i < MAX_TITLES_PER_SESSION + 5; i++) {+ await expect(provider.generateTitle("hi")).resolves.toBe("Title");+ }++ expect(queryMock).toHaveBeenCalledTimes(1);+ expect(closeMock).not.toHaveBeenCalled();+ });++ it("replaces the title session when a title or a /clear fails, or its stream ended", async () => {+ let clears = 0;scriptTitleAgent(async prompt => {if (prompt.endsWith("boom")) {throw new Error("agent crashed");@@ -1138,29 +1194,66 @@ describe("generateTitle", () => {return null;}return [titleResult("Title")];+ }, async () => {+ clears++;+ if (clears === 1) {+ throw new Error("clear crashed");+ }+ return clears === 2 ? null : clearedMessages();});const provider = new ClaudeAgentProvider();- // Full: the next title starts a new session and closes the old one.- for (let i = 0; i <= MAX_TITLES_PER_SESSION; i++) {- await expect(provider.generateTitle("hi")).resolves.toBe("Title");- }+ // A /clear that throws closes the session, and the next title starts another.+ await expect(provider.generateTitle("hi")).resolves.toBe("Title");+ await expect(provider.generateTitle("hi")).resolves.toBe("Title");expect(queryMock).toHaveBeenCalledTimes(2);expect(closeMock).toHaveBeenCalledTimes(1);+ expect(infoLogMock).toHaveBeenCalledWith(expect.stringContaining("clear crashed"));++ // A /clear whose stream ends closes the session too.+ await expect(provider.generateTitle("hi")).resolves.toBe("Title");+ expect(queryMock).toHaveBeenCalledTimes(3);// Failed: the session is closed, the failure logged, and the next title starts another.await expect(provider.generateTitle("boom")).resolves.toBe("");- expect(closeMock).toHaveBeenCalledTimes(2);expect(errorLogMock).toHaveBeenCalledWith(expect.stringContaining("agent crashed"));await expect(provider.generateTitle("hi")).resolves.toBe("Title");- expect(queryMock).toHaveBeenCalledTimes(3);+ expect(queryMock).toHaveBeenCalledTimes(4);// Ended: a stream that stops before its result yields no title, and the next title starts another.await expect(provider.generateTitle("quit")).resolves.toBe("");await expect(provider.generateTitle("hi")).resolves.toBe("Title");- expect(queryMock).toHaveBeenCalledTimes(4);+ expect(queryMock).toHaveBeenCalledTimes(5);});+ it("gives up on a title or a /clear that gets no reply in time, so later titles still run", async () => {+ vi.useFakeTimers();+ try {+ const never = new Promise<null>(() => {});+ scriptTitleAgent(async prompt => (prompt.endsWith("hang") ? never : [titleResult("Title")]), async () => never);+ const provider = new ClaudeAgentProvider();++ const hung = provider.generateTitle("hang");+ await vi.advanceTimersByTimeAsync(TITLE_TIMEOUT_MS);+ await expect(hung).resolves.toBe("");+ expect(errorLogMock).toHaveBeenCalledWith(expect.stringContaining("no reply"));++ const answered = provider.generateTitle("hi");+ await vi.advanceTimersByTimeAsync(0);+ await expect(answered).resolves.toBe("Title");+ const next = provider.generateTitle("hi");+ await vi.advanceTimersByTimeAsync(TITLE_TIMEOUT_MS);+ await expect(next).resolves.toBe("Title");++ expect(queryMock).toHaveBeenCalledTimes(3);+ expect(closeMock).toHaveBeenCalledTimes(2);+ } finally {+ // The last title's /clear hangs as well; let it time out so the next test's titles can run.+ await vi.advanceTimersByTimeAsync(TITLE_TIMEOUT_MS);+ vi.useRealTimers();+ }+ }, 5000);+it("keeps the session after an unsuccessful result, which leaves it in a known state", async () => {scriptTitleAgent(async prompt => (prompt.endsWith("fail")? [{ ...successResult(), subtype: "error_during_execution", is_error: true, errors: [] }]@@ -1183,18 +1276,24 @@ describe("generateTitle", () => {});/**- * A title session: Claude Code in streaming input mode, answering each message- * pushed onto its input with what `reply` returns for its text. `null` ends the- * stream, as a process that exits does.+ * A title session: Claude Code in streaming input mode, answering each title+ * prompt pushed onto its input with what `reply` returns for its text, and each+ * `/clear` with what `clear` returns. `null` ends the stream, as a process that+ * exits does. Returns the texts pushed, in order.*/-function scriptTitleAgent(reply: (prompt: string) => Promise<unknown[] | null>) {+function scriptTitleAgent(+ reply: (prompt: string) => Promise<unknown[] | null>,+ clear: () => Promise<unknown[] | null> = async () => clearedMessages()+): string[] {type Pushed = { message: { content: { text: string }[] } };+ const pushed: string[] = [];queryMock.mockImplementation(({ prompt }: { prompt: string | AsyncIterable<Pushed> }) => {const generator = (async function* () {const input = typeof prompt === "string" ? [prompt] : prompt;- for await (const pushed of input) {- const text = typeof pushed === "string" ? pushed : pushed.message.content.map(block => block.text).join("");- const messages = await reply(text);+ for await (const message of input) {+ const text = typeof message === "string" ? message : message.message.content.map(block => block.text).join("");+ pushed.push(text);+ const messages = await (text === "/clear" ? clear() : reply(text));if (!messages) {return;}@@ -1203,6 +1302,16 @@ function scriptTitleAgent(reply: (prompt: string) => Promise<unknown[] | null>)})();return Object.assign(generator, { setModel: setModelMock, close: closeMock });});+ return pushed;+}++/** What Claude Code streams for a `/clear`, as recorded from CLI 2.1.287. */+function clearedMessages() {+ return [+ { type: "conversation_reset", trigger: "clear", session_id: "sess-1", new_conversation_id: "conv-2" },+ { type: "system", subtype: "init", session_id: "sess-2" },+ { ...successResult("sess-2"), result: "" }+ ];}function titleResult(title: string) {diff --git a/apps/server/src/services/llm/providers/claude_agent.ts b/apps/server/src/services/llm/providers/claude_agent.tsindex c202ea58d1..c4e0cb3867 100644--- a/apps/server/src/services/llm/providers/claude_agent.ts+++ b/apps/server/src/services/llm/providers/claude_agent.ts@@ -20,7 +20,7 @@* with every built-in Claude Code tool (file access, bash, …) disabled.*/-import type { Options as AgentOptions, query as queryFn, SDKAssistantMessage, SDKMessage, SDKUserMessage, SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";+import type { Options as AgentOptions, query as queryFn, SDKAssistantMessage, SDKMessage, SDKResultMessage, SDKUserMessage, SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";import type { ContentBlockParam } from "@anthropic-ai/sdk/resources";import type { LlmMessage, LlmMessagePart, LlmStreamChunk } from "@triliumnext/commons";import { getLog } from "@triliumnext/core";@@ -46,7 +46,7 @@ import {rememberSession as rememberWarmSession,takeWarmSession} from "./claude_session_pool.js";-import { buildHistoryReplay, buildTitlePrompt, cleanTitle, flattenContent, hashTranscript, MAX_TITLES_PER_SESSION } from "./transcript.js";+import { buildHistoryReplay, buildTitlePrompt, cleanTitle, flattenContent, hashTranscript } from "./transcript.js";// Re-exported for existing importers (specs, siblings); the implementations// now live in the shared transcript module.@@ -149,6 +149,16 @@ const TITLE_MODEL = "claude-haiku-4-5-20251001";*/const TITLE_SESSION_KEY = ":title";const TITLE_FINGERPRINT = "title";+/**+ * The title session's system prompt. `/clear` leaves no earlier titles in the+ * history to imitate, so the examples here hold the model to the word limit.+ */+const TITLE_SYSTEM_PROMPT = "You generate short, descriptive titles. A title has at most five words: name the subject "+ + "and leave out filler such as \"Guide\", \"Overview\", \"Basics\" or \"Common Mistakes\". Reply with only the title "+ + "text — no quotes, no punctuation around it. Examples of good titles: \"Garden Shed Wiring Plan\", "+ + "\"Quarterly Budget Review\", \"Fixing Login Timeouts\".";+/** How long a title or a `/clear` waits for its result before the title session is closed. */+export const TITLE_TIMEOUT_MS = 60_000;/** Upper bound on assistant↔tool round-trips within one chat turn. */const MAX_TURNS = 25;@@ -185,8 +195,6 @@ interface SessionEntry {*/const sessionsByChatNote = new Map<string, SessionEntry>();-/** Titles the current title session answered, counting the one in progress. */-let titleCount = 0;/** Settles when the title in progress does; a session answers one prompt at a time. */let titleQueue: Promise<unknown> = Promise.resolve();@@ -644,11 +652,12 @@ export class ClaudeAgentProvider implements LlmProvider {/*** Name a chat after its first message, in the session titles share. Titles- * take turns, because a session answers one prompt at a time.+ * take turns, because a session answers one prompt at a time, and each is+ * followed by a `/clear` that the title does not wait for but the next one does.*/async generateTitle(firstMessage: string): Promise<string> {const title = titleQueue.then(() => this.requestTitle(firstMessage));- titleQueue = title;+ titleQueue = title.then(() => clearTitleSession());return title;}@@ -658,19 +667,9 @@ export class ClaudeAgentProvider implements LlmProvider {try {session = await this.titleSession();await pushUserTurn(session.input, buildTitlePrompt(firstMessage));- // Manual iteration, as in chatChunks(): breaking out of `for await` closes the query.- for (;;) {- const next = await session.query.next();- if (next.done) {- session.closed = true;- return "";- }- const message = next.value;- if (message.type === "result") {- answered = true;- return message.subtype === "success" ? cleanTitle(message.result) : "";- }- }+ const result = await nextResult(session);+ answered = result !== undefined;+ return result?.subtype === "success" ? cleanTitle(result.result) : "";} catch (error) {getLog().error(`Claude Agent title generation failed: ${describeAgentError(error)}`);return "";@@ -684,18 +683,11 @@ export class ClaudeAgentProvider implements LlmProvider {}}- /**- * The warm title session, or a new one on {@link TITLE_MODEL} when there is- * none or the current one reached {@link MAX_TITLES_PER_SESSION}.- */+ /** The warm title session, or a new one on {@link TITLE_MODEL}. */private async titleSession(): Promise<ClaudeSession> {const warm = takeWarmSession(TITLE_SESSION_KEY, TITLE_FINGERPRINT);- if (warm && titleCount < MAX_TITLES_PER_SESSION) {- titleCount++;- return warm;- }if (warm) {- closeSession(TITLE_SESSION_KEY, warm);+ return warm;}const query = await loadQuery();@@ -705,7 +697,7 @@ export class ClaudeAgentProvider implements LlmProvider {prompt: input,options: {...await this.buildBaseOptions({ enableNoteTools: false }),- systemPrompt: "You generate short, descriptive titles. Reply with only the title text — no quotes, no punctuation around it.",+ systemPrompt: TITLE_SYSTEM_PROMPT,model: TITLE_MODEL,maxTurns: 1,persistSession: false@@ -718,7 +710,6 @@ export class ClaudeAgentProvider implements LlmProvider {model: TITLE_MODEL};rememberWarmSession(TITLE_SESSION_KEY, session);- titleCount = 1;return session;}@@ -1056,6 +1047,55 @@ async function* streamSingleUserMessage(content: ContentBlockParam[]): AsyncIteryield { type: "user", message: { role: "user", content }, parent_tool_use_id: null };}+/**+ * Empty the warm title session with `/clear`, which Claude Code runs in the+ * process without a model call, so the next title starts from no history. A+ * `/clear` that fails closes the session, and the next title starts another.+ */+async function clearTitleSession(): Promise<void> {+ const session = takeWarmSession(TITLE_SESSION_KEY, TITLE_FINGERPRINT);+ if (!session) {+ return;+ }+ try {+ await pushUserTurn(session.input, "/clear");+ if (await nextResult(session)) {+ releaseSession(TITLE_SESSION_KEY, session);+ return;+ }+ } catch (error) {+ getLog().info(`Claude Agent provider: clearing the title session failed (${describeAgentError(error)}).`);+ }+ closeSession(TITLE_SESSION_KEY, session);+}++/**+ * Read a title session up to the `result` of the turn just pushed, or undefined+ * when the stream ends first. Throws when no result comes within+ * {@link TITLE_TIMEOUT_MS}, since a wedged `query.next()` might never settle.+ * Iterates by hand, as in `chatChunks()`: breaking out of `for await` closes the query.+ */+async function nextResult(session: ClaudeSession): Promise<SDKResultMessage | undefined> {+ let timer: ReturnType<typeof setTimeout> | undefined;+ const timeout = new Promise<never>((_, reject) => {+ timer = setTimeout(() => reject(new Error(`no reply within ${TITLE_TIMEOUT_MS / 1000} s`)), TITLE_TIMEOUT_MS);+ });+ try {+ for (;;) {+ const next = await Promise.race([session.query.next(), timeout]);+ if (next.done) {+ session.closed = true;+ return undefined;+ }+ if (next.value.type === "result") {+ return next.value;+ }+ }+ } finally {+ clearTimeout(timer);+ }+}+/*** 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