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): 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.tsindex 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.tsindex 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.jsonindex 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.cssindex 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.tsxnew file mode 100644index 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.tsxindex 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 && (<ChatMessagemessage={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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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("./acconst { 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.tsindex 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.tsindex 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.tsindex 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, resetModelCatalogCacheForTeconst 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.tsindex 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 }