Skip to content

Build your personal knowledge base with Trilium Notes

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.ts
index 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.ts
index 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 (impor
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 { 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.ts
index 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[]): AsyncIter
yield { 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