Skip to content

Build your personal knowledge base with Trilium Notes

feat(llm): say in the chat when a turn waits on the agent to start

Elian Doran5a523cf49300
diff --git a/apps/client/src/services/llm_chat.spec.ts b/apps/client/src/services/llm_chat.spec.ts
index 8fc699913d..66ca04c409 100644
--- a/apps/client/src/services/llm_chat.spec.ts
+++ b/apps/client/src/services/llm_chat.spec.ts
@@ -40,6 +40,7 @@ function makeCallbacks(): Record<keyof StreamCallbacks, ReturnType<typeof vi.fn>
onToolResult: vi.fn(),
onCitation: vi.fn(),
onUsage: vi.fn(),
+ onStatus: vi.fn(),
onError: vi.fn(),
onDone: vi.fn()
} as Record<keyof StreamCallbacks, ReturnType<typeof vi.fn>> & StreamCallbacks;
@@ -162,6 +163,7 @@ describe("streamChatCompletion", () => {
it("dispatches every SSE event type to the matching callback", async () => {
const events = [
+ { type: "status", status: "starting_agent" },
{ type: "text", content: "T" },
{ type: "thinking", content: "TH" },
{ type: "tool_input_start", toolCallId: "c1", toolName: "search" },
@@ -186,6 +188,7 @@ describe("streamChatCompletion", () => {
const cb = makeCallbacks();
await streamChatCompletion(messages, config, cb);
+ expect(cb.onStatus).toHaveBeenCalledWith("starting_agent");
expect(cb.onChunk).toHaveBeenCalledWith("T");
expect(cb.onThinking).toHaveBeenCalledWith("TH");
expect(cb.onToolInputStart).toHaveBeenCalledWith("c1", "search");
diff --git a/apps/client/src/services/llm_chat.ts b/apps/client/src/services/llm_chat.ts
index 7e6f54d314..15815c9cf5 100644
--- a/apps/client/src/services/llm_chat.ts
+++ b/apps/client/src/services/llm_chat.ts
@@ -1,4 +1,4 @@
-import type { LlmChatConfig, LlmCitation, LlmErrorDetails, LlmMessage, LlmModelInfo, LlmStreamChunk, LlmUsage, WebSocketMessage } from "@triliumnext/commons";
+import type { LlmChatConfig, LlmCitation, LlmErrorDetails, LlmMessage, LlmModelInfo, LlmStreamChunk, LlmStreamStatus, LlmUsage, WebSocketMessage } from "@triliumnext/commons";
import server from "./server.js";
import { isStandalone, randomString } from "./utils.js";
@@ -58,6 +58,8 @@ export interface StreamCallbacks {
onToolResult?: (toolCallId: string, toolName: string, result: string, isError?: boolean) => void;
onCitation?: (citation: LlmCitation) => void;
onUsage?: (usage: LlmUsage) => void;
+ /** What the turn waits on before its reply starts. */
+ onStatus?: (status: LlmStreamStatus) => void;
/**
* @param error human-readable message.
* @param details provider-call context (status, URL, response body), present only
@@ -250,6 +252,9 @@ function rejectWhenAborted(signal?: AbortSignal): Promise<never> {
*/
async function handleChunk(chunk: LlmStreamChunk, callbacks: StreamCallbacks): Promise<void> {
switch (chunk.type) {
+ case "status":
+ callbacks.onStatus?.(chunk.status);
+ break;
case "text":
callbacks.onChunk(chunk.content);
break;
diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.json
index b16231cf72..dfef9ad412 100644
--- a/apps/client/src/translations/en/translation.json
+++ b/apps/client/src/translations/en/translation.json
@@ -2650,7 +2650,10 @@
"attach_file": "Attach image, PDF, or text file",
"remove_attachment": "Remove attachment",
"attachment_upload_failed": "Failed to upload \"{{name}}\".",
- "attachment_unsupported_type": "\"{{name}}\" isn't a supported attachment type. Use an image (PNG, JPEG, GIF, WebP), a PDF, or a text/source file."
+ "attachment_unsupported_type": "\"{{name}}\" isn't a supported attachment type. Use an image (PNG, JPEG, GIF, WebP), a PDF, or a text/source file.",
+ "stream_status": {
+ "starting_agent": "Starting the agent. This can take a while."
+ }
},
"sidebar_chat": {
"title": "AI Chat",
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.css b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.css
index 9bb1ab4f36..dad39a547d 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.css
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.css
@@ -65,3 +65,12 @@
opacity: 1;
background-color: var(--hover-item-background-color);
}
+
+/* Shown until the first content of a reply arrives, for a turn that waits on something slow. */
+.chat-stream-status {
+ display: flex;
+ align-items: center;
+ gap: 0.5em;
+ color: var(--muted-text-color);
+ font-size: 0.9em;
+}
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.spec.tsx b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.spec.tsx
new file mode 100644
index 0000000000..7052470dff
--- /dev/null
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.spec.tsx
@@ -0,0 +1,59 @@
+import { createRef, render } from "preact";
+import { act } from "preact/test-utils";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../../../services/i18n.js", () => ({
+ t: (key: string) => key
+}));
+vi.mock("../text/ReadOnlyText.js", () => ({
+ ReadOnlyTextContent: ({ html }: { html: string }) => <div className="markdown-stub">{html}</div>
+}));
+
+import ChatMessageList from "./ChatMessageList.js";
+import type { ContentBlock } from "./llm_chat_types.js";
+import type { UseLlmChatReturn } from "./useLlmChat.js";
+
+let host: HTMLElement | undefined;
+
+afterEach(() => {
+ if (host) {
+ render(null, host);
+ host.remove();
+ host = undefined;
+ }
+});
+
+/** Render the list for a streaming turn with nothing stored yet. */
+function renderStreamingTurn(streamingBlocks: ContentBlock[]) {
+ host = document.body.appendChild(document.createElement("div"));
+ const target = host;
+ const chat = {
+ messages: [],
+ isStreaming: true,
+ streamingStatus: "starting_agent",
+ streamingThinking: "",
+ streamingBlocks,
+ pendingCitations: [],
+ retryLast: () => undefined,
+ scrollContainerRef: createRef(),
+ messagesEndRef: createRef(),
+ bottomSpacerRef: createRef(),
+ showScrollToBottom: false,
+ scrollToBottom: () => undefined
+ } as unknown as UseLlmChatReturn;
+ act(() => render(<ChatMessageList chat={chat} emptyStateText="empty" />, target));
+ return target;
+}
+
+describe("ChatMessageList stream status", () => {
+ it("names what the turn waits on until the reply's first content replaces it", () => {
+ const waiting = renderStreamingTurn([]);
+ expect(waiting.querySelector(".chat-stream-status")?.textContent).toBe("llm_chat.stream_status.starting_agent");
+ render(null, waiting);
+ waiting.remove();
+
+ const replying = renderStreamingTurn([ { type: "text", content: "Hello" } ]);
+ expect(replying.querySelector(".markdown-stub")?.textContent).toContain("Hello");
+ expect(replying.querySelector(".chat-stream-status")).toBeNull();
+ });
+});
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx
index 58c231fa38..1e0e72ddc6 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx
@@ -4,6 +4,7 @@ import { useMemo } from "preact/hooks";
import { t } from "../../../services/i18n.js";
import ActionButton from "../../react/ActionButton.js";
+import LoadingSpinner from "../../react/LoadingSpinner.js";
import NoItems from "../../react/NoItems.js";
import ChatMessage from "./ChatMessage.js";
import type { StoredMessage } from "./llm_chat_types.js";
@@ -66,6 +67,12 @@ export default function ChatMessageList({ chat, emptyStateText, className }: Cha
<NoItems icon="bx bx-conversation" text={emptyStateText} />
)}
{storedMessages}
+ {isStreaming && chat.streamingStatus && !thinkingMessage && !streamingMessage && (
+ <div className="chat-stream-status" role="status">
+ <LoadingSpinner />
+ {t(`llm_chat.stream_status.${chat.streamingStatus}`)}
+ </div>
+ )}
{isStreaming && thinkingMessage && (
<ChatMessage
message={thinkingMessage}
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.spec.tsx b/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.spec.tsx
index dc366cff6c..24f0767807 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.spec.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.spec.tsx
@@ -301,4 +301,32 @@ describe("useLlmChat", () => {
});
expect(api().getContent()).toMatchObject({ selectedModel: "mini", selectedProvider: "openai", selectedProviderId: "o_1" });
});
+
+ it("keeps what a turn waits on until the turn ends", async () => {
+ let callbacks: { onStatus: (status: string) => void } | undefined;
+ let finish: () => void = () => undefined;
+ streamChatCompletionMock.mockImplementation(async (_messages, _options, cb) => {
+ callbacks = cb;
+ await new Promise<void>(resolve => { finish = resolve; });
+ cb.onDone();
+ });
+ await mountChat();
+
+ await act(async () => {
+ api().setInput("hi");
+ });
+ await act(async () => {
+ void api().handleSubmit(new Event("submit"));
+ });
+ await act(async () => {
+ callbacks?.onStatus("starting_agent");
+ });
+ expect(api().streamingStatus).toBe("starting_agent");
+
+ await act(async () => {
+ finish();
+ });
+ expect(api().isStreaming).toBe(false);
+ expect(api().streamingStatus).toBeNull();
+ });
});
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts b/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts
index cc147cb274..d05870fc3c 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts
+++ b/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts
@@ -1,4 +1,4 @@
-import { LLM_REASONING_EFFORTS, type LlmCitation, type LlmMessage, type LlmMessagePart, type LlmModelInfo, type LlmReasoningEffort, type LlmUsage } from "@triliumnext/commons";
+import { LLM_REASONING_EFFORTS, type LlmCitation, type LlmMessage, type LlmMessagePart, type LlmModelInfo, type LlmReasoningEffort, type LlmStreamStatus, type LlmUsage } from "@triliumnext/commons";
import { RefObject } from "preact";
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "preact/hooks";
@@ -95,6 +95,8 @@ export interface UseLlmChatReturn {
isStreaming: boolean;
streamingBlocks: ContentBlock[];
streamingThinking: string;
+ /** What the streaming turn waits on before its reply starts, if the server said. */
+ streamingStatus: LlmStreamStatus | null;
pendingCitations: LlmCitation[];
/** Images or files the user has attached but not yet sent. */
pendingAttachments: AttachmentBlock[];
@@ -200,6 +202,7 @@ export function useLlmChat(
// block smoothed via useSmoothStreaming for a steady reveal cadence.
const [targetBlocks, setTargetBlocks] = useState<ContentBlock[]>([]);
const [streamingThinking, setStreamingThinking] = useState("");
+ const [streamingStatus, setStreamingStatus] = useState<LlmStreamStatus | null>(null);
const { displayedText: smoothedTailText, append: smoothAppend, drain: smoothDrain, reset: smoothReset } = useSmoothStreaming();
const [pendingCitations, setPendingCitations] = useState<LlmCitation[]>([]);
const [pendingAttachments, setPendingAttachments] = useState<AttachmentBlock[]>([]);
@@ -555,6 +558,7 @@ export function useLlmChat(
setIsStreaming(true);
setTargetBlocks([]);
setStreamingThinking("");
+ setStreamingStatus(null);
smoothReset();
let thinkingContent = "";
@@ -660,6 +664,7 @@ export function useLlmChat(
setTargetBlocks([]);
setStreamingThinking("");
setPendingCitations([]);
+ setStreamingStatus(null);
setIsStreaming(false);
abortControllerRef.current = null;
}
@@ -668,6 +673,7 @@ export function useLlmChat(
apiMessages,
streamOptions,
{
+ onStatus: setStreamingStatus,
onChunk: (text) => {
// A new text block begins whenever the previous tail is
// anything other than text (or there's nothing yet). In
@@ -788,6 +794,7 @@ export function useLlmChat(
smoothReset();
setTargetBlocks([]);
setStreamingThinking("");
+ setStreamingStatus(null);
setIsStreaming(false);
},
onDone: () => {
@@ -816,6 +823,7 @@ export function useLlmChat(
smoothReset();
setTargetBlocks([]);
setStreamingThinking("");
+ setStreamingStatus(null);
setIsStreaming(false);
abortControllerRef.current = null;
});
@@ -921,6 +929,7 @@ export function useLlmChat(
isStreaming,
streamingBlocks,
streamingThinking,
+ streamingStatus,
pendingCitations,
pendingAttachments,
availableModels,
diff --git a/apps/server/src/services/llm/providers/acp_agent.ts b/apps/server/src/services/llm/providers/acp_agent.ts
index 3bde5af05d..097ee035f9 100644
--- a/apps/server/src/services/llm/providers/acp_agent.ts
+++ b/apps/server/src/services/llm/providers/acp_agent.ts
@@ -376,6 +376,9 @@ export abstract class AcpAgentProvider implements LlmProvider {
let assistantText = "";
try {
+ if (!pool.warm) {
+ yield { type: "status", status: "starting_agent" };
+ }
const acquired = await pool.acquire(connection => this.connect(connection));
lease = acquired;
const client = acquired.client;
diff --git a/apps/server/src/services/llm/providers/acp_client_pool.ts b/apps/server/src/services/llm/providers/acp_client_pool.ts
index 4b6f3920f7..cb8ba8e41f 100644
--- a/apps/server/src/services/llm/providers/acp_client_pool.ts
+++ b/apps/server/src/services/llm/providers/acp_client_pool.ts
@@ -87,6 +87,11 @@ export class AcpClientPool {
}
}
+ /** Whether a live process is ready, so {@link acquire} hands it out without starting one. */
+ get warm(): boolean {
+ return this.pooled?.client.alive === true;
+ }
+
/** Return a lease. The client is reaped once no turn has used it for {@link IDLE_TIMEOUT_MS}. */
release(): void {
this.activeTurns = Math.max(0, this.activeTurns - 1);
diff --git a/apps/server/src/services/llm/providers/antigravity_agent.spec.ts b/apps/server/src/services/llm/providers/antigravity_agent.spec.ts
index c0d9c542b8..3e658e665d 100644
--- a/apps/server/src/services/llm/providers/antigravity_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/antigravity_agent.spec.ts
@@ -103,7 +103,12 @@ const { createUpdateCollector, resetAcpAgentStateForTests } = await import("./ac
const { AntigravityAgentProvider, buildAntigravityEnv, buildAntigravityModelList, decideAntigravityPermission } = await import("./antigravity_agent.js");
const { parseBuildLabel } = await vi.importActual<typeof import("./antigravity_binary.js")>("./antigravity_binary.js");
+/** The reply chunks of a turn, without the status that precedes a cold start (see {@link collectAll}). */
async function collect(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
+ return (await collectAll(iterable)).filter(chunk => chunk.type !== "status");
+}
+
+async function collectAll(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
const chunks: LlmStreamChunk[] = [];
for await (const chunk of iterable) {
chunks.push(chunk);
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 b76dc5c8c1..28877e1905 100644
--- a/apps/server/src/services/llm/providers/claude_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.spec.ts
@@ -110,7 +110,12 @@ function makeQuery(messages: unknown[]) {
return Object.assign(generator, { setModel: setModelMock, close: closeMock });
}
+/** The reply chunks of a turn, without the status that precedes a cold start (see {@link collectAll}). */
async function collect(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
+ return (await collectAll(iterable)).filter(chunk => chunk.type !== "status");
+}
+
+async function collectAll(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
const chunks: LlmStreamChunk[] = [];
for await (const chunk of iterable) {
chunks.push(chunk);
@@ -259,8 +264,10 @@ describe("ClaudeAgentProvider.chatChunks", () => {
[textDelta("second reply"), successResult("sess-A")]
]);
- // Turn 1 — no history, no mapping: plain prompt, no resume.
- await collect(provider.chatChunks([{ role: "user", content: "first question" }], config));
+ // Turn 1 — no history, no mapping: plain prompt, no resume. Starting the
+ // subprocess is announced before anything else.
+ const first = await collectAll(provider.chatChunks([{ role: "user", content: "first question" }], config));
+ expect(first[0]).toEqual({ type: "status", status: "starting_agent" });
expect(queryMock).toHaveBeenCalledTimes(1);
const call = queryMock.mock.calls[0][0];
@@ -268,7 +275,7 @@ describe("ClaudeAgentProvider.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([
+ const second = await collectAll(provider.chatChunks([
{ role: "user", content: "first question" },
{ role: "assistant", content: "first reply" },
{ role: "user", content: "second question" }
@@ -276,6 +283,7 @@ describe("ClaudeAgentProvider.chatChunks", () => {
expect(queryMock).toHaveBeenCalledTimes(1);
expect(second).toContainEqual({ type: "text", content: "second reply" });
+ expect(second.some(chunk => chunk.type === "status")).toBe(false);
const pushed = pushedMessages(call.prompt).map(m => (m.message.content[0] as { text: string }).text);
expect(pushed).toEqual(["first question", "second question"]);
});
diff --git a/apps/server/src/services/llm/providers/claude_agent.ts b/apps/server/src/services/llm/providers/claude_agent.ts
index 6f3b989caa..2ce0681b2b 100644
--- a/apps/server/src/services/llm/providers/claude_agent.ts
+++ b/apps/server/src/services/llm/providers/claude_agent.ts
@@ -421,6 +421,7 @@ export class ClaudeAgentProvider implements LlmProvider {
session.model = model;
}
} else {
+ yield { type: "status", status: "starting_agent" };
const input = new Pushable<SDKUserMessage>();
session = {
query: query({
diff --git a/apps/server/src/services/llm/providers/copilot_agent.spec.ts b/apps/server/src/services/llm/providers/copilot_agent.spec.ts
index aaf589a28a..db9be570b6 100644
--- a/apps/server/src/services/llm/providers/copilot_agent.spec.ts
+++ b/apps/server/src/services/llm/providers/copilot_agent.spec.ts
@@ -147,7 +147,12 @@ const { buildCopilotModelList, CopilotAgentProvider, resetModelCatalogCacheForTe
const decidePermission = (request: Parameters<typeof denyPermission>[0]) => denyPermission(request, "Copilot Agent provider");
+/** The reply chunks of a turn, without the status that precedes a cold start (see {@link collectAll}). */
async function collect(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
+ return (await collectAll(iterable)).filter(chunk => chunk.type !== "status");
+}
+
+async function collectAll(iterable: AsyncIterable<LlmStreamChunk>): Promise<LlmStreamChunk[]> {
const chunks: LlmStreamChunk[] = [];
for await (const chunk of iterable) {
chunks.push(chunk);
@@ -732,6 +737,17 @@ describe("CopilotAgentProvider.chatChunks", () => {
describe("CopilotAgentProvider keep-alive", () => {
beforeEach(resetFakes);
+ it("says the agent is starting before a turn that has to start it, and only then", async () => {
+ const provider = new CopilotAgentProvider();
+ const starting = { type: "status", status: "starting_agent" };
+
+ expect((await collectAll(provider.chatChunks([userMessage("hi")], {})))[0]).toEqual(starting);
+ expect(await collectAll(provider.chatChunks([userMessage("hi")], {}))).not.toContainEqual(starting);
+
+ FakeAcpClient.current?.die();
+ expect((await collectAll(provider.chatChunks([userMessage("hi")], {})))[0]).toEqual(starting);
+ });
+
it("reuses one agent process across turns, chats and titles, starting it once", async () => {
const startSpy = vi.spyOn(FakeAcpClient, "start").mockClear();
const provider = new CopilotAgentProvider();
diff --git a/packages/commons/src/lib/llm_api.ts b/packages/commons/src/lib/llm_api.ts
index d2c826e4cc..4cb19f1238 100644
--- a/packages/commons/src/lib/llm_api.ts
+++ b/packages/commons/src/lib/llm_api.ts
@@ -200,11 +200,19 @@ export interface LlmErrorDetails {
responseBody?: string;
}
+/**
+ * What a turn is waiting on before its reply starts. The client names it in
+ * the chat until the first content of the reply arrives.
+ * - `starting_agent`: a subscription agent's CLI is being started.
+ */
+export type LlmStreamStatus = "starting_agent";
+
/**
* Stream chunk types for real-time SSE updates.
* Defines the protocol between server and client.
*/
export type LlmStreamChunk =
+ | { type: "status"; status: LlmStreamStatus }
| { type: "text"; content: string }
| { type: "thinking"; content: string }
| { type: "tool_input_start"; toolCallId: string; toolName: string }