Skip to content

Build your personal knowledge base with Trilium Notes

feat(llm): ask the user before every tool call of an API provider

Elian Doran6d743912451f
diff --git a/apps/client/src/services/llm_chat.spec.ts b/apps/client/src/services/llm_chat.spec.ts
index 66ca04c409..889eb4cf01 100644
--- a/apps/client/src/services/llm_chat.spec.ts
+++ b/apps/client/src/services/llm_chat.spec.ts
@@ -37,6 +37,7 @@ function makeCallbacks(): Record<keyof StreamCallbacks, ReturnType<typeof vi.fn>
onToolInputStart: vi.fn(),
onToolInputDelta: vi.fn(),
onToolUse: vi.fn(),
+ onToolApprovalRequest: vi.fn(),
onToolResult: vi.fn(),
onCitation: vi.fn(),
onUsage: vi.fn(),
@@ -116,10 +117,26 @@ describe("streamChatCompletion", () => {
expect(init.method).toBe("POST");
expect((init.headers as Record<string, string>)["Content-Type"]).toBe("application/json");
expect((init.headers as Record<string, string>)["x-csrf-token"]).toBe("tok");
- expect(init.body).toBe(JSON.stringify({ messages, config }));
+ expect(JSON.parse(init.body as string)).toEqual({ streamId: expect.any(String), messages, config });
expect(cb.onChunk).toHaveBeenCalledWith("hello");
});
+ it("hands a waiting tool call to the chat with a way to answer it under the stream's id", async () => {
+ const request = { toolCallId: "c1", toolName: "delete_note", toolInput: { noteId: "a" } };
+ const fetchMock = vi.fn(async () => makeStreamResponse([`data: ${JSON.stringify({ type: "tool_approval_request", ...request })}\n`]));
+ vi.stubGlobal("fetch", fetchMock);
+ server.post = vi.fn(async () => ({ answered: true })) as typeof server.post;
+
+ const cb = makeCallbacks();
+ await streamChatCompletion(messages, config, cb);
+ expect(cb.onToolApprovalRequest).toHaveBeenCalledExactlyOnceWith(request, expect.any(Function));
+
+ const answer = cb.onToolApprovalRequest.mock.calls[0][1] as (approved: boolean) => Promise<void>;
+ await answer(false);
+ const { streamId } = JSON.parse((fetchMock.mock.calls[0] as unknown as [string, RequestInit])[1].body as string);
+ expect(server.post).toHaveBeenCalledExactlyOnceWith("llm-chat/tool-approval", { streamId, toolCallId: "c1", approved: false });
+ });
+
it("rethrows an AbortError from fetch (user stopped)", async () => {
const abort = new DOMException("aborted", "AbortError");
vi.stubGlobal("fetch", vi.fn(async () => { throw abort; }));
diff --git a/apps/client/src/services/llm_chat.ts b/apps/client/src/services/llm_chat.ts
index 15815c9cf5..e26135dd15 100644
--- a/apps/client/src/services/llm_chat.ts
+++ b/apps/client/src/services/llm_chat.ts
@@ -1,4 +1,16 @@
-import type { LlmChatConfig, LlmCitation, LlmErrorDetails, LlmMessage, LlmModelInfo, LlmStreamChunk, LlmStreamStatus, LlmUsage, WebSocketMessage } from "@triliumnext/commons";
+import type {
+ LlmChatConfig,
+ LlmCitation,
+ LlmErrorDetails,
+ LlmMessage,
+ LlmModelInfo,
+ LlmStreamChunk,
+ LlmStreamStatus,
+ LlmToolApprovalAnswer,
+ LlmToolApprovalRequest,
+ LlmUsage,
+ WebSocketMessage
+} from "@triliumnext/commons";
import server from "./server.js";
import { isStandalone, randomString } from "./utils.js";
@@ -55,6 +67,14 @@ export interface StreamCallbacks {
onToolInputStart?: (toolCallId: string, toolName: string) => void;
onToolInputDelta?: (toolCallId: string, delta: string) => void;
onToolUse?: (toolCallId: string, toolName: string, input: Record<string, unknown>) => void;
+ /**
+ * A tool call waits for the user to allow or deny it. `answer` sends the decision, and the call
+ * then runs or reports itself declined in a `tool_result`.
+ */
+ onToolApprovalRequest?: (
+ request: LlmToolApprovalRequest,
+ answer: (approved: boolean) => Promise<void>
+ ) => void;
onToolResult?: (toolCallId: string, toolName: string, result: string, isError?: boolean) => void;
onCitation?: (citation: LlmCitation) => void;
onUsage?: (usage: LlmUsage) => void;
@@ -76,6 +96,9 @@ export interface StreamCallbacks {
* {@link StreamCallbacks} and the promise settles when it is over, rejecting with
* an `AbortError` if `abortSignal` fired. Which transport is used depends on what
* the backend can be reached over — see {@link streamChatOverMessages}.
+ *
+ * The stream id is minted here for either transport: the backend finds the turn by
+ * it when the user answers one of its tool calls.
*/
export function streamChatCompletion(
messages: LlmMessage[],
@@ -83,9 +106,15 @@ export function streamChatCompletion(
callbacks: StreamCallbacks,
abortSignal?: AbortSignal
): Promise<void> {
+ const streamId = randomString(12);
return isStandalone
- ? streamChatOverMessages(messages, config, callbacks, abortSignal)
- : streamChatOverSse(messages, config, callbacks, abortSignal);
+ ? streamChatOverMessages(streamId, messages, config, callbacks, abortSignal)
+ : streamChatOverSse(streamId, messages, config, callbacks, abortSignal);
+}
+
+/** Tell a running turn whether the user allows one of its tool calls. */
+async function answerToolApproval(answer: LlmToolApprovalAnswer): Promise<void> {
+ await server.post("llm-chat/tool-approval", answer);
}
/**
@@ -93,6 +122,7 @@ export function streamChatCompletion(
* that stays open for the whole completion.
*/
async function streamChatOverSse(
+ streamId: string,
messages: LlmMessage[],
config: LlmChatConfig,
callbacks: StreamCallbacks,
@@ -107,7 +137,7 @@ async function streamChatOverSse(
...headers,
"Content-Type": "application/json"
} as HeadersInit,
- body: JSON.stringify({ messages, config }),
+ body: JSON.stringify({ streamId, messages, config }),
signal: abortSignal
});
} catch (e) {
@@ -148,7 +178,7 @@ async function streamChatOverSse(
for (const line of lines) {
if (line.startsWith("data: ")) {
try {
- await handleChunk(JSON.parse(line.slice(6)), callbacks);
+ await handleChunk(streamId, JSON.parse(line.slice(6)), callbacks);
} catch (e) {
console.error("Failed to parse SSE data line:", line, e);
}
@@ -173,18 +203,18 @@ async function streamChatOverSse(
* request here only starts the completion; the chunks arrive as `llm-stream`
* messages and an `llm-stream-end` says when there are no more.
*
- * The stream id is minted here, before the completion is asked for, so the
+ * The stream id is minted before the completion is asked for, so the
* subscription is already in place when the first chunk lands. Every tab receives
* the messages — only the leader holds the worker, and the rest hear it through a
* relay — so the id is also what makes a tab keep just its own.
*/
async function streamChatOverMessages(
+ streamId: string,
messages: LlmMessage[],
config: LlmChatConfig,
callbacks: StreamCallbacks,
abortSignal?: AbortSignal
): Promise<void> {
- const streamId = randomString(12);
let resolveEnd: () => void = () => undefined;
const ended = new Promise<void>((resolve) => { resolveEnd = resolve; });
// Handlers are dispatched without being awaited, so nothing else keeps the
@@ -193,7 +223,7 @@ async function streamChatOverMessages(
const onMessage = (message: WebSocketMessage) => {
if (message.type === "llm-stream" && message.streamId === streamId) {
- handled = handled.then(() => handleChunk(message.chunk, callbacks));
+ handled = handled.then(() => handleChunk(streamId, message.chunk, callbacks));
// Marks the link handled the moment it is made. `await handled` below
// still rethrows, but without this a chunk handler that threw would sit
// as an unhandled rejection until the stream ends — and in the
@@ -250,7 +280,11 @@ function rejectWhenAborted(signal?: AbortSignal): Promise<never> {
* Dispatch one chunk to the callbacks. Shared by both transports, so a chunk means
* the same thing however it arrived.
*/
-async function handleChunk(chunk: LlmStreamChunk, callbacks: StreamCallbacks): Promise<void> {
+async function handleChunk(
+ streamId: string,
+ chunk: LlmStreamChunk,
+ callbacks: StreamCallbacks
+): Promise<void> {
switch (chunk.type) {
case "status":
callbacks.onStatus?.(chunk.status);
@@ -276,6 +310,12 @@ async function handleChunk(chunk: LlmStreamChunk, callbacks: StreamCallbacks): P
// state before we process the result.
await new Promise((r) => setTimeout(r, 1));
break;
+ case "tool_approval_request": {
+ const { toolCallId, toolName, toolInput } = chunk;
+ callbacks.onToolApprovalRequest?.({ toolCallId, toolName, toolInput }, (approved) =>
+ answerToolApproval({ streamId, toolCallId, approved }));
+ break;
+ }
case "tool_result":
callbacks.onToolResult?.(chunk.toolCallId, chunk.toolName, chunk.result, chunk.isError);
await new Promise((r) => setTimeout(r, 1));
diff --git a/apps/client/src/services/llm_chat_standalone.spec.ts b/apps/client/src/services/llm_chat_standalone.spec.ts
index 0023f0e1f7..ff1fad201d 100644
--- a/apps/client/src/services/llm_chat_standalone.spec.ts
+++ b/apps/client/src/services/llm_chat_standalone.spec.ts
@@ -34,6 +34,7 @@ function makeCallbacks(): Record<keyof StreamCallbacks, ReturnType<typeof vi.fn>
onToolInputStart: vi.fn(),
onToolInputDelta: vi.fn(),
onToolUse: vi.fn(),
+ onToolApprovalRequest: vi.fn(),
onToolResult: vi.fn(),
onCitation: vi.fn(),
onUsage: vi.fn(),
@@ -109,6 +110,20 @@ describe("streamChatCompletion in standalone", () => {
expect(cb.onToolUse.mock.invocationCallOrder[0]).toBeLessThan(cb.onChunk.mock.invocationCallOrder[0]);
});
+ it("answers a waiting tool call under the id the stream was started with", async () => {
+ const cb = makeCallbacks();
+ const streaming = streamChatCompletion(messages, config, cb);
+ await Promise.resolve();
+
+ broadcast(chunk({ type: "tool_approval_request", toolCallId: "c1", toolName: "delete_note", toolInput: {} }));
+ broadcast(end);
+ await streaming;
+
+ const answer = cb.onToolApprovalRequest.mock.calls[0]?.[1] as ((approved: boolean) => Promise<void>) | undefined;
+ await answer?.(true);
+ expect(posts.at(-1)).toEqual([ "llm-chat/tool-approval", { streamId: "stream1", toolCallId: "c1", approved: true } ]);
+ });
+
it("reports a failure to start the completion, and does not wait for a stream that never began", async () => {
server.post = vi.fn(async () => { throw JSON.stringify({ message: "No LLM providers configured." }); }) as typeof server.post;
diff --git a/apps/client/src/translations/en/translation.json b/apps/client/src/translations/en/translation.json
index c11781f024..ebd9de1f08 100644
--- a/apps/client/src/translations/en/translation.json
+++ b/apps/client/src/translations/en/translation.json
@@ -2691,7 +2691,12 @@
"manage_search_providers": "Manage search providers…",
"web_search_builtin_unsupported": "This model has no built-in web search. Choose a search provider instead.",
"web_search_provider_unsupported": "This model's provider searches the web with its own tools.",
- "searched_with": "Searched with {{name}}"
+ "searched_with": "Searched with {{name}}",
+ "tool_approval_prompt": "Allow this tool call?",
+ "tool_approval_allow": "Allow",
+ "tool_approval_deny": "Deny",
+ "tool_approval_pending": "waiting for approval",
+ "tool_approval_declined": "denied"
},
"sidebar_chat": {
"title": "AI Chat",
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 66d529502d..4cbb5dcd2e 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ChatMessageList.tsx
@@ -8,6 +8,7 @@ import LoadingSpinner from "../../react/LoadingSpinner.js";
import NoItems from "../../react/NoItems.js";
import ChatMessage from "./ChatMessage.js";
import type { ContentBlock, StoredMessage } from "./llm_chat_types.js";
+import { ToolApprovalContext } from "./ToolCallCard.js";
import type { UseLlmChatReturn } from "./useLlmChat.js";
/** How long a streaming reply goes without changing before the list says it is still working. */
@@ -72,13 +73,15 @@ export default function ChatMessageList({ chat, emptyStateText, className }: Cha
</div>
)}
{isStreaming && streamingMessage && (
- <ChatMessage
- message={streamingMessage}
- isStreaming
- streamStatus={isStreamIdle && !showsOwnProgress(chat.streamingBlocks)
- ? t("llm_chat.stream_status.still_working")
- : undefined}
- />
+ <ToolApprovalContext.Provider value={chat.answerToolCall}>
+ <ChatMessage
+ message={streamingMessage}
+ isStreaming
+ streamStatus={isStreamIdle && !showsOwnProgress(chat.streamingBlocks)
+ ? t("llm_chat.stream_status.still_working")
+ : undefined}
+ />
+ </ToolApprovalContext.Provider>
)}
<div ref={chat.messagesEndRef} className="chat-messages-end" aria-hidden="true" />
<div ref={chat.bottomSpacerRef} className="chat-bottom-spacer" aria-hidden="true" />
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.css b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.css
index 9d0de5a57b..14bb23211b 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.css
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.css
@@ -12,7 +12,8 @@
.llm-chat-tool-call-detail,
.llm-chat-tool-call-attachment-title,
.llm-chat-tool-call-count,
-.llm-chat-tool-call-result-count {
+.llm-chat-tool-call-result-count,
+.llm-chat-tool-call-approval-badge {
font-size: 0.75rem;
font-weight: 400;
opacity: 0.75;
@@ -66,16 +67,19 @@
overflow-wrap: anywhere;
}
-/* Raw JSON arriving from the LLM, shown until it parses. The blinking caret marks it as still
- arriving. */
-.llm-chat-tool-call-streaming {
+.llm-chat-tool-call-streaming,
+.llm-chat-tool-call-input {
margin: 0;
max-height: 300px;
overflow: auto;
font-size: 0.8rem;
white-space: pre-wrap;
overflow-wrap: anywhere;
+}
+/* Raw JSON arriving from the LLM, shown until it parses. The blinking caret marks it as still
+ arriving. */
+.llm-chat-tool-call-streaming {
&::after {
content: "▍";
color: var(--muted-text-color);
@@ -113,3 +117,15 @@
--masked-icon-size: 0.9rem;
}
}
+
+/* The left margin matches `.expandable-line-body` in ExpandableCard.css, so the bar lines up with
+ the body of the call above it. */
+.llm-chat-tool-approval {
+ display: flex;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 0.5rem;
+ margin: 0.25rem 0 0.5rem 0.45rem;
+ padding-left: 0.85rem;
+ font-size: 0.85rem;
+}
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.spec.tsx b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.spec.tsx
index cb7f70fc43..155ec01197 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.spec.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.spec.tsx
@@ -38,7 +38,7 @@ vi.mock("../../react/NoteLink.js", () => ({
<a className="note-link-stub" href="#" onClick={onClick}>{notePath}</a>
}));
-import ToolCallCard from "./ToolCallCard.js";
+import ToolCallCard, { ToolApprovalContext } from "./ToolCallCard.js";
import type { ToolCall } from "./llm_chat_types.js";
let host: HTMLElement | undefined;
@@ -53,10 +53,15 @@ afterEach(() => {
}
});
-function renderCard(toolCalls: ToolCall[]) {
+function renderCard(toolCalls: ToolCall[], answer?: (toolCallId: string, approved: boolean) => void) {
host = document.body.appendChild(document.createElement("div"));
const target = host;
- act(() => render(<ToolCallCard toolCalls={toolCalls} />, target));
+ act(() => render(
+ <ToolApprovalContext.Provider value={answer}>
+ <ToolCallCard toolCalls={toolCalls} />
+ </ToolApprovalContext.Provider>,
+ target
+ ));
return target;
}
@@ -770,4 +775,53 @@ describe("ToolCallCard", () => {
expect(link?.getAttribute("target")).toBe("_blank");
expect(line?.querySelector(".llm-chat-note-result-preview")?.textContent).toBe("The page describes Trilium.");
});
+
+ describe("approval", () => {
+ const PENDING: ToolCall = { id: "c1", toolName: "rename_note", input: { noteId: "a", newTitle: "B" }, approval: "pending" };
+ const buttons = (target: HTMLElement) =>
+ [ ...target.querySelectorAll<HTMLButtonElement>(".llm-chat-tool-approval button") ];
+
+ it("opens a waiting call on its input, and answers it from the buttons below", () => {
+ const answer = vi.fn();
+ const target = renderCard([ PENDING ], answer);
+
+ const line = target.querySelector<HTMLDetailsElement>("details.llm-chat-tool-call");
+ expect(line?.open).toBe(true);
+ expect(JSON.parse(line?.querySelector(".llm-chat-tool-call-input")?.textContent ?? "null")).toEqual(PENDING.input);
+ expect(line?.querySelector(".llm-chat-tool-call-approval-badge")?.textContent).toBe("llm_chat.tool_approval_pending");
+
+ const [ deny, allow ] = buttons(target);
+ expect([ deny?.textContent?.trim(), allow?.textContent?.trim() ]).toEqual([ "llm_chat.tool_approval_deny", "llm_chat.tool_approval_allow" ]);
+ act(() => allow?.click());
+ expect(answer).toHaveBeenCalledExactlyOnceWith("c1", true);
+ act(() => deny?.click());
+ expect(answer).toHaveBeenLastCalledWith("c1", false);
+ });
+
+ it("shows what a waiting writing call would write instead of its raw input", () => {
+ const target = renderCard([ {
+ id: "c1", toolName: "create_note", input: { parentNoteId: "p", title: "T", type: "code", mime: "text/plain", content: "hello" }, approval: "pending"
+ } ], vi.fn());
+ expect(target.querySelector(".code-block-stub")?.textContent).toBe("hello");
+ expect(target.querySelector(".llm-chat-tool-call-input")).toBeNull();
+ expect(buttons(target)).toHaveLength(2);
+ });
+
+ it("opens a group holding a waiting call, and offers no buttons outside the streaming reply", () => {
+ const target = renderCard([ { ...PENDING, id: "c0", approval: undefined, result: "{}" }, PENDING ]);
+ expect(target.querySelector<HTMLDetailsElement>("details.llm-chat-tool-call-group")?.open).toBe(true);
+ expect(target.querySelector(".llm-chat-tool-approval")).toBeNull();
+ });
+
+ it("marks a denied call as denied rather than failed", () => {
+ const target = renderCard([ {
+ ...PENDING, approval: "declined", result: JSON.stringify({ error: "The user declined this tool call." }), isError: true
+ } ]);
+ const line = target.querySelector(".llm-chat-tool-call");
+ expect(line?.classList.contains("llm-chat-tool-call-error")).toBe(false);
+ expect(line?.querySelector(".llm-chat-tool-call-approval-badge")?.textContent).toBe("llm_chat.tool_approval_declined");
+ expect(target.querySelector(".llm-chat-tool-call-error-badge, .llm-chat-tool-call-error-message")).toBeNull();
+ expect(target.querySelector(".bx-block")).not.toBeNull();
+ });
+ });
});
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.tsx b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.tsx
index 2841666947..cc4a283539 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallCard.tsx
@@ -1,10 +1,13 @@
import "./ToolCallCard.css";
+import { createContext } from "preact";
+import { useContext } from "preact/hooks";
import { Trans } from "react-i18next";
import appContext from "../../../components/app_context.js";
import { t } from "../../../services/i18n.js";
import ActionButton from "../../react/ActionButton.js";
+import Button from "../../react/Button.js";
import MaskedIcon from "../../react/MaskedIcon.js";
import { NewNoteLink } from "../../react/NoteLink.js";
import { providerIconUrl } from "../options/llm/provider_icons.js";
@@ -13,6 +16,13 @@ import { ExpandableSection } from "./ExpandableCard.js";
import { isFailedToolCall, type ToolCall } from "./llm_chat_types.js";
import { ExternalLink, getToolCallView, type ToolCallView } from "./ToolCallViews.js";
+/**
+ * Allows or denies a tool call of the running turn that waits for the user. Provided only around
+ * the reply that streams, since a saved reply has nothing left to answer.
+ */
+export const ToolApprovalContext =
+ createContext<((toolCallId: string, approved: boolean) => void) | undefined>(undefined);
+
interface ToolCallContext {
/** The primary note the tool operates on or created. */
noteId: string | null;
@@ -112,6 +122,8 @@ function toolNameIcon(toolName: string): string {
}
function toolCallIcon(toolCall: ToolCall) {
+ if (toolCall.approval === "pending") return "bx bx-help-circle";
+ if (toolCall.approval === "declined") return "bx bx-block";
if (isFailedToolCall(toolCall)) return "bx bx-error-circle";
if (!toolCall.result) return "bx bx-loader-alt bx-spin";
const searchProvider = readSearchProvider(toolCall);
@@ -180,6 +192,13 @@ function ToolCallLabel({ toolCall, view }: { toolCall: ToolCall; view: ToolCallV
</span>
)}
{view?.summary && <span className="llm-chat-tool-call-result-count">{view.summary}</span>}
+ {toolCall.approval && (
+ <span className="llm-chat-tool-call-approval-badge">
+ {toolCall.approval === "pending"
+ ? t("llm_chat.tool_approval_pending")
+ : t("llm_chat.tool_approval_declined")}
+ </span>
+ )}
{hasError && <span className="llm-chat-tool-call-error-badge">{t("llm_chat.tool_error")}</span>}
</>
);
@@ -212,10 +231,27 @@ function NoteRef({ noteId, parentNoteId, move }: {
* streams, the diff of an `edit_note_content` call, why the call failed, or the view
* `getToolCallView()` builds for the tools that have one. The raw input and
* result are in the dialog the debug button opens.
+ *
+ * A call that waits for the user is open, showing what it would do (its view, or else its input),
+ * with the buttons that allow or deny it below.
*/
function ToolCallSection({ toolCall }: { toolCall: ToolCall }) {
+ const section = <ToolCallDisclosure toolCall={toolCall} />;
+ if (toolCall.approval !== "pending") {
+ return section;
+ }
+ return (
+ <div className="llm-chat-tool-call-pending">
+ {section}
+ <ToolApprovalBar toolCallId={toolCall.id} />
+ </div>
+ );
+}
+
+function ToolCallDisclosure({ toolCall }: { toolCall: ToolCall }) {
const hasError = isFailedToolCall(toolCall);
const isStreamingInput = toolCall.inputStreaming !== undefined;
+ const isPending = toolCall.approval === "pending";
// The partial JSON of a streaming input does not parse, so the diff waits for the whole input.
const noteContentEdits = !isStreamingInput && toolCall.toolName === "edit_note_content"
@@ -224,13 +260,19 @@ function ToolCallSection({ toolCall }: { toolCall: ToolCall }) {
const editedNoteId = typeof toolCall.input.noteId === "string" ? toolCall.input.noteId : undefined;
const errorMessage = hasError && toolCall.result ? getErrorMessage(toolCall.result) : null;
const view = isStreamingInput ? null : getToolCallView(toolCall);
+ // A waiting call with nothing else to show what it would do shows its input.
+ const pendingInput = isPending && !noteContentEdits && !view?.body
+ ? JSON.stringify(toolCall.input, null, 2)
+ : null;
const className = `llm-chat-tool-call ${hasError ? "llm-chat-tool-call-error" : ""}`;
const icon = toolCallIcon(toolCall);
const label = <ToolCallLabel toolCall={toolCall} view={view} />;
const debugButton = <ToolCallDebugButton toolCall={toolCall} />;
+ const open = isPending
+ || (noteContentEdits ? isSmallEdit(noteContentEdits) : isStreamingInput || undefined);
- if (!isStreamingInput && !noteContentEdits && !errorMessage && !view?.body) {
+ if (!isStreamingInput && !noteContentEdits && !errorMessage && !view?.body && !pendingInput) {
return (
<div className={`expandable-line ${className}`}>
<div className="expandable-line-header">
@@ -249,7 +291,7 @@ function ToolCallSection({ toolCall }: { toolCall: ToolCall }) {
actions={debugButton}
variant="line"
className={className}
- open={noteContentEdits ? isSmallEdit(noteContentEdits) : isStreamingInput || undefined}
+ open={open}
>
{isStreamingInput && <pre className="llm-chat-tool-call-streaming">{toolCall.inputStreaming}</pre>}
{noteContentEdits && (
@@ -259,6 +301,7 @@ function ToolCallSection({ toolCall }: { toolCall: ToolCall }) {
)}
{errorMessage && <p className="llm-chat-tool-call-error-message">{errorMessage}</p>}
{view?.body}
+ {pendingInput && <pre className="llm-chat-tool-call-input">{pendingInput}</pre>}
</ExpandableSection>
);
}
@@ -283,10 +326,12 @@ function ToolCallDebugButton({ toolCall }: { toolCall: ToolCall }) {
function ToolCallGroupSection({ toolCalls }: { toolCalls: ToolCall[] }) {
const first = toolCalls[0];
const anyPending = toolCalls.some(tc => !tc.result);
+ const anyAwaitingApproval = toolCalls.some(tc => tc.approval === "pending");
const anyError = toolCalls.some(isFailedToolCall);
const searchProvider = readSearchProvider(first);
- const icon = anyPending ? "bx bx-loader-alt bx-spin"
+ const icon = anyAwaitingApproval ? "bx bx-help-circle"
+ : anyPending ? "bx bx-loader-alt bx-spin"
: searchProvider && toolCalls.every(tc => readSearchProvider(tc)?.type === searchProvider.type)
? <SearchProviderIcon {...searchProvider} />
: toolNameIcon(first.toolName);
@@ -300,7 +345,13 @@ function ToolCallGroupSection({ toolCalls }: { toolCalls: ToolCall[] }) {
);
return (
- <ExpandableSection variant="line" icon={icon} label={label} className="llm-chat-tool-call llm-chat-tool-call-group">
+ <ExpandableSection
+ variant="line"
+ icon={icon}
+ label={label}
+ className="llm-chat-tool-call llm-chat-tool-call-group"
+ open={anyAwaitingApproval || undefined}
+ >
{toolCalls.map((tc, idx) => (
<ToolCallSection key={tc.id ?? idx} toolCall={tc} />
))}
@@ -337,3 +388,33 @@ export default function ToolCallCard({ toolCalls }: { toolCalls: ToolCall[] }) {
</div>
);
}
+
+/** Asks the user whether a waiting tool call can run. */
+function ToolApprovalBar({ toolCallId }: { toolCallId: string }) {
+ const answer = useContext(ToolApprovalContext);
+ if (!answer) {
+ return null;
+ }
+
+ return (
+ <div
+ className="llm-chat-tool-approval"
+ role="group"
+ aria-label={t("llm_chat.tool_approval_prompt")}
+ >
+ <span>{t("llm_chat.tool_approval_prompt")}</span>
+ <Button
+ size="small"
+ text={t("llm_chat.tool_approval_deny")}
+ onClick={() => answer(toolCallId, false)}
+ />
+ <Button
+ size="small"
+ kind="primary"
+ icon="bx bx-check"
+ text={t("llm_chat.tool_approval_allow")}
+ onClick={() => answer(toolCallId, true)}
+ />
+ </div>
+ );
+}
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallViews.tsx b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallViews.tsx
index a6a61972f2..30c7894f2b 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/ToolCallViews.tsx
+++ b/apps/client/src/widgets/type_widgets/llm_chat/ToolCallViews.tsx
@@ -30,9 +30,12 @@ export interface ToolCallView {
body?: ComponentChildren;
}
-/** The view of a successful call to a tool that has one, or `null` to show the bare line. */
+/**
+ * The view of a successful or pending call to a tool that has one, or `null` to show the bare
+ * line.
+ */
export function getToolCallView(toolCall: ToolCall): ToolCallView | null {
- if (isFailedToolCall(toolCall)) return null;
+ if (isFailedToolCall(toolCall) || toolCall.approval === "declined") return null;
// What a writing tool writes is in its input, so it shows before the result arrives.
if (toolCall.toolName === "create_note") {
diff --git a/apps/client/src/widgets/type_widgets/llm_chat/llm_chat_types.ts b/apps/client/src/widgets/type_widgets/llm_chat/llm_chat_types.ts
index 0ad746d87b..dd64e7b816 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/llm_chat_types.ts
+++ b/apps/client/src/widgets/type_widgets/llm_chat/llm_chat_types.ts
@@ -19,6 +19,8 @@ export interface ToolCall {
inputStreaming?: string;
result?: string;
isError?: boolean;
+ /** `pending` while the call waits for the user to allow it, `declined` once they denied it. */
+ approval?: "pending" | "declined";
}
/** A block of text content (rendered as Markdown for assistant messages). */
@@ -116,10 +118,12 @@ export function trimToFirstUserMessage<T extends { role: string }>(messages: T[]
*/
/**
* Whether a tool call failed: flagged so by the provider, or answered with the `{ error }` a note tool
- * returns. The result covers chats saved while a provider did not pass the flag on.
+ * returns. The result covers chats saved while a provider did not pass the flag on. A call the user
+ * denied never ran, so it did not fail.
*/
export function isFailedToolCall(toolCall: ToolCall): boolean {
- return !!toolCall.isError || isToolErrorResult(toolCall.result);
+ return toolCall.approval !== "declined"
+ && (!!toolCall.isError || isToolErrorResult(toolCall.result));
}
export function getMessageToolCalls(message: StoredMessage): ToolCall[] {
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 96d23b7338..912273608d 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
@@ -446,4 +446,55 @@ describe("useLlmChat", () => {
expect(api().isStreaming).toBe(false);
expect(api().streamingStatus).toBeNull();
});
+
+ it("holds a tool call for the user's answer, sends that answer once, and keeps a denial in the reply", async () => {
+ type Answer = (approved: boolean) => Promise<void>;
+ let callbacks: {
+ onToolApprovalRequest: (request: { toolCallId: string; toolName: string; toolInput: Record<string, unknown> }, answer: Answer) => void;
+ onToolResult: (toolCallId: string, toolName: string, result: string, isError?: boolean) => void;
+ } | undefined;
+ let finish: () => void = () => undefined;
+ streamChatCompletionMock.mockImplementation(async (_messages, _options, cb) => {
+ callbacks = cb;
+ await new Promise<void>(resolve => { finish = resolve; });
+ cb.onDone();
+ });
+ const answers = { c1: vi.fn<Answer>(async () => {}), c2: vi.fn<Answer>(async () => {}) };
+ await mountChat();
+ await act(async () => {
+ api().setInput("tidy up");
+ });
+ await act(async () => {
+ void api().handleSubmit(new Event("submit"));
+ });
+
+ // A request can arrive before the `tool_use` of its call, so it brings the call along.
+ await act(async () => {
+ callbacks?.onToolApprovalRequest({ toolCallId: "c1", toolName: "delete_note", toolInput: { noteId: "a" } }, answers.c1);
+ callbacks?.onToolApprovalRequest({ toolCallId: "c2", toolName: "delete_note", toolInput: { noteId: "b" } }, answers.c2);
+ });
+ expect(api().streamingBlocks).toMatchObject([
+ { type: "tool_call", toolCall: { id: "c1", input: { noteId: "a" }, approval: "pending" } },
+ { type: "tool_call", toolCall: { id: "c2", approval: "pending" } }
+ ]);
+
+ await act(async () => {
+ api().answerToolCall("c1", false);
+ api().answerToolCall("c1", true);
+ callbacks?.onToolResult("c1", "delete_note", JSON.stringify({ error: "declined" }), true);
+ });
+ expect(answers.c1).toHaveBeenCalledExactlyOnceWith(false);
+ expect(api().streamingBlocks[0]).toMatchObject({ toolCall: { id: "c1", approval: "declined" } });
+
+ // Stopped while waiting: the call that was never answered is no longer waiting.
+ await act(async () => {
+ finish();
+ });
+ expect(api().messages.at(-1)?.content).toMatchObject([
+ { toolCall: { id: "c1", approval: "declined" } },
+ { toolCall: { id: "c2", approval: undefined, result: "[Stopped]" } }
+ ]);
+ api().answerToolCall("c2", true);
+ expect(answers.c2).not.toHaveBeenCalled();
+ });
});
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 b356359ca9..aee331caa9 100644
--- a/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts
+++ b/apps/client/src/widgets/type_widgets/llm_chat/useLlmChat.ts
@@ -10,7 +10,16 @@ import { useTriliumEvent } from "../../react/hooks.js";
import { estimateTokens, quantizeDraftTokens } from "./chat_context_usage.js";
import { stripQuoteSources } from "./chat_quote.js";
import { conversationForRegenerate } from "./chat_regenerate.js";
-import { type ContentBlock, type FileBlock, type ImageBlock, type LlmChatContent, type StoredMessage, type TextFileBlock, trimToFirstUserMessage } from "./llm_chat_types.js";
+import {
+ type ContentBlock,
+ type FileBlock,
+ type ImageBlock,
+ type LlmChatContent,
+ type StoredMessage,
+ type TextFileBlock,
+ type ToolCall,
+ trimToFirstUserMessage
+} from "./llm_chat_types.js";
import { useSmoothStreaming } from "./useSmoothStreaming.js";
/** A user-supplied attachment waiting to be sent with the next message. */
@@ -171,6 +180,8 @@ export interface UseLlmChatReturn {
refreshModels: () => void;
/** Stop the current generation */
stopStreaming: () => void;
+ /** Allow or deny a tool call of the running turn that waits for the user. */
+ answerToolCall: (toolCallId: string, approved: boolean) => void;
/** Re-run the last turn after a failed response (drops the trailing error message) */
retryLast: () => void;
/** Regenerate the last reply: re-run from the last user message, dropping the reply that followed */
@@ -231,6 +242,8 @@ export function useLlmChat(
const scrollContainerRef = useRef<HTMLDivElement>(null);
const bottomSpacerRef = useRef<HTMLDivElement>(null);
const abortControllerRef = useRef<AbortController | null>(null);
+ // How to answer each tool call of the running turn that waits for the user, by call id.
+ const toolApprovalAnswersRef = useRef(new Map<string, (approved: boolean) => void>());
const anchorRafRef = useRef<number | null>(null);
// A one-shot scroll to run after the next messages render: "anchor" parks a fresh
// reply near the top (sending/retrying), "bottom" jumps to the latest content
@@ -580,6 +593,23 @@ export function useLlmChat(
const citations: LlmCitation[] = [];
let usage: LlmUsage | undefined;
+ toolApprovalAnswersRef.current.clear();
+
+ /** Apply `change` to the tool call `toolCallId`. Returns `false` if the reply has none. */
+ function updateToolCall(toolCallId: string, change: Partial<ToolCall>): boolean {
+ for (let i = contentBlocks.length - 1; i >= 0; i--) {
+ const block = contentBlocks[i];
+ if (block.type === "tool_call" && block.toolCall.id === toolCallId) {
+ contentBlocks[i] = {
+ type: "tool_call",
+ toolCall: { ...block.toolCall, ...change }
+ };
+ return true;
+ }
+ }
+ return false;
+ }
+
/** Get or create the last text block to append streaming text to. */
function lastTextBlock(): ContentBlock & { type: "text" } {
const last = contentBlocks[contentBlocks.length - 1];
@@ -650,7 +680,8 @@ export function useLlmChat(
...block.toolCall,
inputStreaming: undefined,
result: "[Stopped]",
- isError: true
+ isError: true,
+ approval: undefined
}
};
}
@@ -670,6 +701,7 @@ export function useLlmChat(
setTargetBlocks([]);
setPendingCitations([]);
setStreamingStatus(null);
+ toolApprovalAnswersRef.current.clear();
setIsStreaming(false);
abortControllerRef.current = null;
}
@@ -766,6 +798,30 @@ export function useLlmChat(
});
setTargetBlocks([...contentBlocks]);
},
+ onToolApprovalRequest: ({ toolCallId, toolName, toolInput }, answer) => {
+ // The request can arrive before the `tool_use` chunk of its call.
+ const waiting: Partial<ToolCall> = {
+ input: toolInput,
+ inputStreaming: undefined,
+ approval: "pending"
+ };
+ if (!updateToolCall(toolCallId, waiting)) {
+ smoothDrain();
+ const toolCall: ToolCall = {
+ id: toolCallId, toolName, input: toolInput, approval: "pending"
+ };
+ contentBlocks.push({ type: "tool_call", toolCall });
+ }
+ toolApprovalAnswersRef.current.set(toolCallId, (approved) => {
+ toolApprovalAnswersRef.current.delete(toolCallId);
+ updateToolCall(toolCallId, { approval: approved ? undefined : "declined" });
+ setTargetBlocks([...contentBlocks]);
+ answer(approved).catch((e: unknown) => {
+ console.error("Failed to answer the tool call:", e);
+ });
+ });
+ setTargetBlocks([...contentBlocks]);
+ },
onToolResult: (toolCallId, _toolName, result, isError) => {
// Replace the matching block with a new object so Preact sees the change.
for (let i = contentBlocks.length - 1; i >= 0; i--) {
@@ -913,6 +969,11 @@ export function useLlmChat(
}
}, [handleSubmit]);
+ /** Allow or deny a tool call of the running turn that waits for the user. */
+ const answerToolCall = useCallback((toolCallId: string, approved: boolean) => {
+ toolApprovalAnswersRef.current.get(toolCallId)?.(approved);
+ }, []);
+
/** Stop the current generation by aborting the SSE connection. */
const stopStreaming = useCallback(() => {
if (abortControllerRef.current) {
@@ -993,6 +1054,7 @@ export function useLlmChat(
clearMessages,
refreshModels,
stopStreaming,
+ answerToolCall,
retryLast,
regenerateLastReply
};
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI.html
index 5dd9b769d7..90fe18ccba 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI.html
@@ -262,13 +262,31 @@
<p>When the reply stops moving for a couple of seconds while the AI is still
at work, for example while it reads what a tool returned, a <em>Still working…</em> line
appears under it until the next part of the reply arrives.</p>
-<aside class="admonition warning">
- <p>Currently there is <strong>no permission management</strong> implemented
- for note tools, meaning that the LLM could potentially remove existing
- notes or clutter the tree with notes. Generally most actions are easily
- reversible (deleting the notes, restoring deleted notes, reverting modifications
- to a note), but there are some that are harder to revert (e.g. setting
- an attribute because there is no attribute history).</p>
+<h4>Approving tool calls</h4>
+<p>Before the AI runs a tool, the chat asks whether to allow it. The tool's
+ line opens on what the call would do (the text it would write, the changes
+ of an edit, or else the values it would send to the tool), with <em>Allow</em> and <em>Deny</em> buttons
+ below it and <em>waiting for approval</em> beside the tool's name. The reply
+ waits until you answer.</p>
+<ul>
+ <li>To let the call run, press <em>Allow</em>.</li>
+ <li>To refuse it, press <em>Deny</em>. The AI is told that you declined, and
+ its reply carries on without the call, which is marked <em>denied</em>.</li>
+ <li>Stopping the reply denies every call that is still waiting.</li>
+</ul>
+<p>Every tool call asks, including the ones that only read: searching notes,
+ reading a note or an attachment, and reading a web page through a search
+ provider. A model's built-in web search runs on the provider's side and
+ does not ask.</p>
+<aside class="admonition important">
+ <p>The <a class="reference-link" href="#root/_help_eFhxp9laTW1S">Subscription-based providers</a> (Claude
+ Code, GitHub Copilot, Google Antigravity and OpenAI Codex) don't ask yet:
+ their tool calls run without approval.</p>
+</aside>
+<aside class="admonition note">
+ <p>Most changes you allow can be undone: a deleted note can be restored,
+ and an edit reverted from its revision. Setting an attribute is harder
+ to undo, since attributes have no history.</p>
</aside>
<aside class="admonition note">
<p>Gemini can't use its built-in search while note access is on. While it
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI/Privacy.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI/Privacy.html
index 11de033373..a4c1dec87f 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI/Privacy.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/AI/Privacy.html
@@ -67,8 +67,10 @@
<ul>
<li>Tools let the model search your tree and read notes, attributes and attachments
beyond the current one.</li>
- <li>It decides what to fetch; there is no per-note permission system, so the
- reachable scope is your whole tree.</li>
+ <li>It decides what to fetch, and each call waits for you to allow it (except
+ with the <a class="reference-link" href="#root/_help_eFhxp9laTW1S">Subscription-based providers</a>).
+ There is no per-note permission system, so the reachable scope is your
+ whole tree.</li>
</ul>
</li>
<li><strong>Attachments and mentions</strong>, when you add them: images,
diff --git a/apps/server/src/routes/api/llm_chat.spec.ts b/apps/server/src/routes/api/llm_chat.spec.ts
index 84b24881f6..b13e0062a6 100644
--- a/apps/server/src/routes/api/llm_chat.spec.ts
+++ b/apps/server/src/routes/api/llm_chat.spec.ts
@@ -6,13 +6,16 @@ const state = vi.hoisted(() => ({
/** Milliseconds to wait before yielding chunk i. Missing entries wait 0. */
delaysMs: [] as number[],
/** The signal runChat was handed, so the disconnect wiring can be asserted. */
- signal: undefined as AbortSignal | undefined
+ signal: undefined as AbortSignal | undefined,
+ /** The stream id runChat was handed. */
+ streamId: undefined as string | undefined
}));
// The completion itself is core's and tested there; what this route adds is the
// SSE framing around it, so only the chunk source is faked.
vi.mock("@triliumnext/core/src/services/llm/chat.js", () => ({
- async *runChat(_messages: unknown, _config: unknown, signal?: AbortSignal) {
+ async *runChat(streamId: string, _messages: unknown, _config: unknown, signal?: AbortSignal) {
+ state.streamId = streamId;
state.signal = signal;
for (const [index, chunk] of state.chunks.entries()) {
const wait = state.delaysMs[index] ?? 0;
@@ -53,21 +56,30 @@ function fakeRes({ withFlush = false } = {}) {
};
}
-function req(body: unknown) { return { body } as unknown as Request; }
+/** A request for the stream `s1`, which `body` can override. */
+function req(body: object) { return { body: { streamId: "s1", ...body } } as unknown as Request; }
describe("streamChat", () => {
afterEach(() => {
state.chunks = [];
state.delaysMs = [];
state.signal = undefined;
+ state.streamId = undefined;
});
- it("returns 400 for an empty messages array, without opening a stream", async () => {
- const r = fakeRes();
- await llmChatRoute.streamChat(req({ messages: [] }), r.res);
- expect(r.statusCode).toBe(400);
- expect(r.jsonBody).toEqual({ error: "messages array is required" });
- expect(r.writes).toEqual([]);
+ it("returns 400 for a missing stream id or an empty messages array, without opening a stream", async () => {
+ const noId = fakeRes();
+ await llmChatRoute.streamChat(req({ streamId: undefined, messages: [{ role: "user", content: "hi" }] }), noId.res);
+ expect(noId.statusCode).toBe(400);
+ expect(noId.jsonBody).toEqual({ error: "streamId is required" });
+ expect(noId.writes).toEqual([]);
+
+ const noMessages = fakeRes();
+ await llmChatRoute.streamChat(req({ messages: [] }), noMessages.res);
+ expect(noMessages.statusCode).toBe(400);
+ expect(noMessages.jsonBody).toEqual({ error: "messages array is required" });
+ expect(noMessages.writes).toEqual([]);
+ expect(state.streamId).toBeUndefined();
});
it("writes each chunk as an SSE event, flushes it, and ends the response", async () => {
@@ -83,6 +95,7 @@ describe("streamChat", () => {
]);
expect(r.flushes).toBe(2);
expect(r.ended).toBe(true);
+ expect(state.streamId).toBe("s1");
});
it("ends the response and streams without a flush method available", async () => {
diff --git a/apps/server/src/routes/api/llm_chat.ts b/apps/server/src/routes/api/llm_chat.ts
index b1f23d709c..dd31523018 100644
--- a/apps/server/src/routes/api/llm_chat.ts
+++ b/apps/server/src/routes/api/llm_chat.ts
@@ -3,6 +3,8 @@ import type { LlmProviderConfig } from "@triliumnext/core/src/services/llm/types
import type { Request, Response } from "express";
interface ChatRequest {
+ /** The id the client gave the turn, by which it answers the turn's tool calls. */
+ streamId: string;
messages: LlmMessage[];
config?: LlmProviderConfig;
}
@@ -28,8 +30,12 @@ export const SSE_HEARTBEAT_FRAME = ":\n\n";
* writes an SSE comment (`:\n\n`) that the client ignores.
*/
async function streamChat(req: Request, res: Response) {
- const { messages, config = {} } = req.body as ChatRequest;
+ const { streamId, messages, config = {} } = req.body as ChatRequest;
+ if (!streamId) {
+ res.status(400).json({ error: "streamId is required" });
+ return;
+ }
if (!messages || !Array.isArray(messages) || messages.length === 0) {
res.status(400).json({ error: "messages array is required" });
return;
@@ -76,7 +82,7 @@ async function streamChat(req: Request, res: Response) {
// the provider SDKs land in lazy chunks (the same convention as
// getProviderModels in core's routes/api/llm.ts).
const { runChat } = await import("@triliumnext/core/src/services/llm/chat.js");
- for await (const chunk of runChat(messages, config, abortController.signal)) {
+ for await (const chunk of runChat(streamId, messages, config, abortController.signal)) {
writeFrame(`data: ${JSON.stringify(chunk)}\n\n`);
heartbeat.reset();
}
diff --git a/docs/User Guide/User Guide/AI.md b/docs/User Guide/User Guide/AI.md
index 49113be853..a2e778acb2 100644
--- a/docs/User Guide/User Guide/AI.md
+++ b/docs/User Guide/User Guide/AI.md
@@ -156,8 +156,21 @@ Each tool the AI uses appears in the chat as a single line naming the tool and t
When the reply stops moving for a couple of seconds while the AI is still at work, for example while it reads what a tool returned, a _Still working…_ line appears under it until the next part of the reply arrives.
-> [!WARNING]
-> Currently there is **no permission management** implemented for note tools, meaning that the LLM could potentially remove existing notes or clutter the tree with notes. Generally most actions are easily reversible (deleting the notes, restoring deleted notes, reverting modifications to a note), but there are some that are harder to revert (e.g. setting an attribute because there is no attribute history).
+#### Approving tool calls
+
+Before the AI runs a tool, the chat asks whether to allow it. The tool's line opens on what the call would do (the text it would write, the changes of an edit, or else the values it would send to the tool), with _Allow_ and _Deny_ buttons below it and _waiting for approval_ beside the tool's name. The reply waits until you answer.
+
+* To let the call run, press _Allow_.
+* To refuse it, press _Deny_. The AI is told that you declined, and its reply carries on without the call, which is marked _denied_.
+* Stopping the reply denies every call that is still waiting.
+
+Every tool call asks, including the ones that only read: searching notes, reading a note or an attachment, and reading a web page through a search provider. A model's built-in web search runs on the provider's side and does not ask.
+
+> [!IMPORTANT]
+> The <a class="reference-link" href="AI/Providers/Subscription-based%20providers.md">Subscription-based providers</a> (Claude Code, GitHub Copilot, Google Antigravity and OpenAI Codex) don't ask yet: their tool calls run without approval.
+
+> [!NOTE]
+> Most changes you allow can be undone: a deleted note can be restored, and an edit reverted from its revision. Setting an attribute is harder to undo, since attributes have no history.
> [!NOTE]
> Gemini can't use its built-in search while note access is on. While it is, the built-in search choice in the _Tools_ menu is disabled and says why; a search provider works with note access on.
diff --git a/docs/User Guide/User Guide/AI/Privacy.md b/docs/User Guide/User Guide/AI/Privacy.md
index 3216c060c2..f1be3238f5 100644
--- a/docs/User Guide/User Guide/AI/Privacy.md
+++ b/docs/User Guide/User Guide/AI/Privacy.md
@@ -28,7 +28,7 @@ This is the reason the provider list is grouped this way, and why Trilium pre-se
* Notes above a size threshold send a size hint instead of the text, and the model must call a tool to read further.
* **Any note the model asks for, when note access is enabled.**
* Tools let the model search your tree and read notes, attributes and attachments beyond the current one.
- * It decides what to fetch; there is no per-note permission system, so the reachable scope is your whole tree.
+ * It decides what to fetch, and each call waits for you to allow it (except with the <a class="reference-link" href="Providers/Subscription-based%20providers.md">Subscription-based providers</a>). There is no per-note permission system, so the reachable scope is your whole tree.
* **Attachments and mentions**, when you add them: images, PDFs and text files are sent to the provider, and an `@` mention makes that note fetchable.
* **Your search query**, when web search is enabled, the model's search terms reach the provider's own search infrastructure, or the search provider chosen in the _Tools_ menu (Brave Search, Tavily, Exa, Serper, Perplexity or your SearXNG instance).
* **The pages the model reads**, when web search goes through a search provider: Trilium fetches each page the model asks for from the site itself, so the site sees a request from the machine running Trilium. The page's text is then sent to the model's provider.
diff --git a/packages/commons/src/lib/llm_api.ts b/packages/commons/src/lib/llm_api.ts
index 1971036762..d3079369bf 100644
--- a/packages/commons/src/lib/llm_api.ts
+++ b/packages/commons/src/lib/llm_api.ts
@@ -249,6 +249,21 @@ export function isToolErrorResult(result: unknown): boolean {
return typeof value === "object" && value !== null && !Array.isArray(value) && "error" in value;
}
+/** A tool call that waits for the user to allow or deny it. */
+export interface LlmToolApprovalRequest {
+ toolCallId: string;
+ toolName: string;
+ toolInput: Record<string, unknown>;
+}
+
+/** The user's answer to a {@link LlmToolApprovalRequest}, posted to `/api/llm-chat/tool-approval`. */
+export interface LlmToolApprovalAnswer {
+ /** The id the client gave the turn when it started it. */
+ streamId: string;
+ toolCallId: string;
+ approved: boolean;
+}
+
/**
* Stream chunk types for real-time SSE updates.
* Defines the protocol between server and client.
@@ -260,6 +275,7 @@ export type LlmStreamChunk =
| { type: "tool_input_start"; toolCallId: string; toolName: string }
| { type: "tool_input_delta"; toolCallId: string; delta: string }
| { type: "tool_use"; toolCallId: string; toolName: string; toolInput: Record<string, unknown> }
+ | ({ type: "tool_approval_request" } & LlmToolApprovalRequest)
| { type: "tool_result"; toolCallId: string; toolName: string; result: string; isError?: boolean }
| { type: "citation"; citation: LlmCitation }
| { type: "usage"; usage: LlmUsage }
diff --git a/packages/trilium-core/src/routes/api/llm.spec.ts b/packages/trilium-core/src/routes/api/llm.spec.ts
index 2b362f7efb..3186b6c507 100644
--- a/packages/trilium-core/src/routes/api/llm.spec.ts
+++ b/packages/trilium-core/src/routes/api/llm.spec.ts
@@ -13,6 +13,8 @@ const state = vi.hoisted(() => ({
chatThrows: undefined as unknown,
/** The signal the completion was handed, so the abort route can be asserted. */
signal: undefined as AbortSignal | undefined,
+ /** The stream id the completion was handed. */
+ streamId: undefined as string | undefined,
/** Keeps the faked completion running until it is aborted, as a real one would. */
holdUntilAborted: false,
/** Every message broadcast while a stream ran. */
@@ -30,7 +32,8 @@ vi.mock("../../services/llm/index.js", () => ({
}));
vi.mock("../../services/llm/chat.js", () => ({
- async *runChat(_messages: unknown, _config: unknown, signal?: AbortSignal) {
+ async *runChat(streamId: string, _messages: unknown, _config: unknown, signal?: AbortSignal) {
+ state.streamId = streamId;
state.signal = signal;
if (state.chatThrows !== undefined) throw state.chatThrows;
for (const c of state.chunks) yield c;
@@ -40,10 +43,11 @@ vi.mock("../../services/llm/chat.js", () => ({
}
}));
+import { closeToolApprovals, openToolApprovals } from "../../services/llm/tool_approval.js";
import { getLog } from "../../services/log.js";
import ws from "../../services/ws.js";
-import { abortChatStream, getProviderModels, startChatStream } from "./llm.js";
+import { abortChatStream, answerToolCall, getProviderModels, startChatStream } from "./llm.js";
/**
* Poll until the completion — which runs detached from the request that started
@@ -91,6 +95,7 @@ afterEach(() => {
chunks: [],
chatThrows: undefined,
signal: undefined,
+ streamId: undefined,
holdUntilAborted: false,
sent: []
});
@@ -138,6 +143,7 @@ describe("startChatStream", () => {
{ type: "llm-stream", streamId: "s1", chunk: { type: "done" } },
{ type: "llm-stream-end", streamId: "s1" }
]);
+ expect(state.streamId).toBe("s1");
});
it("rejects a request that could not be matched back to a stream", () => {
@@ -199,3 +205,25 @@ describe("abortChatStream", () => {
expect(() => abortChatStream({ body: {} })).not.toThrow();
});
});
+
+describe("answerToolCall", () => {
+ afterEach(() => closeToolApprovals("s1"));
+
+ it("settles the call waiting in the turn, and reports an answer that came too late", async () => {
+ const approvals = openToolApprovals("s1");
+ const decision = approvals?.request({ toolCallId: "c1", toolName: "create_note", toolInput: {} });
+
+ expect(answerToolCall({ body: { streamId: "s1", toolCallId: "c1", approved: true } })).toEqual({ answered: true });
+ await expect(decision).resolves.toBe(true);
+
+ // Answered already, a call of another turn, and a turn that has ended.
+ expect(answerToolCall({ body: { streamId: "s1", toolCallId: "c1", approved: false } })).toEqual({ answered: false });
+ expect(answerToolCall({ body: { streamId: "s2", toolCallId: "c1", approved: true } })).toEqual({ answered: false });
+ });
+
+ it("rejects an answer that names no call or gives no decision", () => {
+ expect(() => answerToolCall({ body: { streamId: "s1", toolCallId: "c1" } })).toThrow(/approved are required/);
+ expect(() => answerToolCall({ body: { streamId: "s1", approved: true } })).toThrow(/approved are required/);
+ expect(() => answerToolCall({ body: { toolCallId: "c1", approved: true } })).toThrow(/approved are required/);
+ });
+});
diff --git a/packages/trilium-core/src/routes/api/llm.ts b/packages/trilium-core/src/routes/api/llm.ts
index dc4dfa6e50..0cb2a1fb30 100644
--- a/packages/trilium-core/src/routes/api/llm.ts
+++ b/packages/trilium-core/src/routes/api/llm.ts
@@ -1,6 +1,6 @@
/**
* The LLM endpoints' handlers. Where each is *registered* differs by runtime, so
- * only {@link getProviderModels} is in the shared route table.
+ * only {@link getProviderModels} and {@link answerToolCall} are in the shared route table.
*
* Streaming has no shared form. The server and the desktop app answer
* `/api/llm-chat/stream` with Server-Sent Events (that route lives in
@@ -11,10 +11,11 @@
* browser_routes.ts — and the chunks come back over the WebSocket-style channel.
*/
-import type { LlmMessage } from "@triliumnext/commons";
+import type { LlmMessage, LlmToolApprovalAnswer } from "@triliumnext/commons";
import { ValidationError } from "../../errors.js";
import * as cls from "../../services/context.js";
+import { answerToolApproval } from "../../services/llm/tool_approval.js";
import type { LlmProviderConfig } from "../../services/llm/types.js";
import { getLog } from "../../services/log.js";
import { safeExtractMessageAndStackFromError } from "../../services/utils/index.js";
@@ -90,6 +91,19 @@ export function startChatStream(req: { body: ChatStreamRequest }) {
return {};
}
+/**
+ * Pass on the user's answer to a tool call that waits in a running turn, whichever
+ * transport streams it. `answered` is `false` when the turn has ended or the call
+ * was already answered, which a second click or a stopped turn can cause.
+ */
+export function answerToolCall(req: { body: Partial<LlmToolApprovalAnswer> }) {
+ const { streamId, toolCallId, approved } = req.body ?? {};
+ if (!streamId || !toolCallId || typeof approved !== "boolean") {
+ throw new ValidationError("streamId, toolCallId and approved are required");
+ }
+ return { answered: answerToolApproval(streamId, toolCallId, approved) };
+}
+
/** Stop a completion started by {@link startChatStream}; unknown ids are a no-op. */
export function abortChatStream(req: { body: { streamId?: string } }) {
activeStreams.get(req.body?.streamId ?? "")?.abort();
@@ -127,7 +141,7 @@ async function streamToClients(
// The tools a completion may call write notes, which needs a context of
// its own: the request that started this one has long since answered.
await cls.init(async () => {
- for await (const chunk of runChat(messages, config, signal)) {
+ for await (const chunk of runChat(streamId, messages, config, signal)) {
ws.sendMessageToAllClients({ type: "llm-stream", streamId, chunk });
}
});
@@ -147,5 +161,6 @@ async function streamToClients(
export default {
getProviderModels,
startChatStream,
+ answerToolCall,
abortChatStream
};
diff --git a/packages/trilium-core/src/routes/index.ts b/packages/trilium-core/src/routes/index.ts
index 00121b8b86..75afc3a7d3 100644
--- a/packages/trilium-core/src/routes/index.ts
+++ b/packages/trilium-core/src/routes/index.ts
@@ -254,7 +254,10 @@ export function buildSharedApiRoutes({ route, asyncRoute, asyncRouteWithoutTrans
// The server and the desktop app answer `/api/llm-chat/stream` with Server-Sent
// Events; standalone, whose bridge cannot hold a response open, registers
// `llmRoute.startChatStream` itself. See `apps/standalone`'s browser_routes.ts.
+ // Answering a tool call is here: it reaches the turn by its stream id, whichever
+ // transport streams it.
asyncApiRoute(PST, "/api/llm-chat/provider-models", llmRoute.getProviderModels);
+ apiRoute(PST, "/api/llm-chat/tool-approval", llmRoute.answerToolCall);
apiRoute(GET, "/api/autocomplete", autocompleteApiRoute.getAutocomplete);
diff --git a/packages/trilium-core/src/services/llm/chat.spec.ts b/packages/trilium-core/src/services/llm/chat.spec.ts
index 456707d2ec..d1ec848a2b 100644
--- a/packages/trilium-core/src/services/llm/chat.spec.ts
+++ b/packages/trilium-core/src/services/llm/chat.spec.ts
@@ -9,6 +9,8 @@ const state = vi.hoisted(() => ({
/** When true the fake provider is chunk-native, and records the signal it was handed. */
chunkNative: false,
chunkSignal: undefined as AbortSignal | undefined,
+ /** When true the chunk-native provider asks about a tool call and reports the answer. */
+ asksApproval: false,
/** Records how runChat resolved the provider. */
providerIdRequested: undefined as string | undefined,
providerTypeRequested: undefined as string | undefined,
@@ -29,9 +31,15 @@ vi.mock("./index.js", () => {
return {};
},
chatChunks: state.chunkNative
- ? async function* (_messages: unknown, _config: unknown, signal?: AbortSignal) {
+ ? async function* (_messages: unknown, config: LlmProviderConfig, signal?: AbortSignal) {
state.chunkSignal = signal;
for (const c of state.chunks) yield c;
+ if (state.asksApproval) {
+ const toolInput = { title: "New" };
+ yield { type: "tool_use", toolCallId: "c1", toolName: "create_note", toolInput };
+ const approved = await config.toolApprovals?.request({ toolCallId: "c1", toolName: "create_note", toolInput });
+ yield { type: "text", content: `approved: ${approved}` };
+ }
}
: undefined,
getAvailableModels: () => state.availableModels,
@@ -63,11 +71,13 @@ vi.mock("../log.js", async (importOriginal) => ({
}));
import { runChat } from "./chat.js";
+import { answerToolApproval } from "./tool_approval.js";
+import type { LlmProviderConfig } from "./types.js";
/** Drain a completion into an array, which is how every assertion here reads it. */
async function collect(messages: LlmMessage[], config: object = {}, signal?: AbortSignal): Promise<LlmStreamChunk[]> {
const collected: LlmStreamChunk[] = [];
- for await (const chunk of runChat(messages, config, signal)) {
+ for await (const chunk of runChat("s1", messages, config, signal)) {
collected.push(chunk);
}
return collected;
@@ -94,6 +104,7 @@ describe("runChat", () => {
chatThrows: undefined,
chunkNative: false,
chunkSignal: undefined,
+ asksApproval: false,
providerIdRequested: undefined,
providerTypeRequested: undefined,
chatConfig: undefined
@@ -170,13 +181,61 @@ describe("runChat", () => {
state.chunks = [{ type: "text", content: "a" }, { type: "text", content: "b" }];
const controller = new AbortController();
const collected: LlmStreamChunk[] = [];
- for await (const chunk of runChat(HELLO, {}, controller.signal)) {
+ for await (const chunk of runChat("s1", HELLO, {}, controller.signal)) {
collected.push(chunk);
controller.abort();
}
expect(collected).toEqual([{ type: "text", content: "a" }]);
});
+ describe("tool approval", () => {
+ const TOOL_USE = { type: "tool_use", toolCallId: "c1", toolName: "create_note", toolInput: { title: "New" } };
+ const REQUEST = { type: "tool_approval_request", toolCallId: "c1", toolName: "create_note", toolInput: { title: "New" } };
+
+ it("announces a waiting call while it holds the stream, and resumes once the user answers", async () => {
+ state.chunkNative = true;
+ state.asksApproval = true;
+ const turn = runChat("s1", HELLO, {});
+
+ expect((await turn.next()).value).toEqual(TOOL_USE);
+ expect((await turn.next()).value).toEqual(REQUEST);
+ expect(answerToolApproval("s1", "c1", true)).toBe(true);
+ expect((await turn.next()).value).toEqual({ type: "text", content: "approved: true" });
+ expect((await turn.next()).done).toBe(true);
+ // The turn has ended, so nothing waits under its id any more.
+ expect(answerToolApproval("s1", "c1", true)).toBe(false);
+ });
+
+ it("declines a waiting call when the turn is stopped", async () => {
+ state.chunkNative = true;
+ state.asksApproval = true;
+ const controller = new AbortController();
+ const turn = runChat("s1", HELLO, {}, controller.signal);
+
+ expect((await turn.next()).value).toEqual(TOOL_USE);
+ expect((await turn.next()).value).toEqual(REQUEST);
+ const resumed = turn.next();
+ controller.abort();
+ // Stopped, the turn ends at its next chunk; the call itself was declined.
+ expect((await resumed).done).toBe(true);
+ expect(answerToolApproval("s1", "c1", true)).toBe(false);
+ });
+
+ it("refuses a stream id that another running turn holds", async () => {
+ state.chunkNative = true;
+ state.asksApproval = true;
+ const first = runChat("s1", HELLO, {});
+ await first.next();
+
+ expect(await collect(HELLO)).toEqual([{ type: "error", error: "Stream 's1' is already running." }]);
+
+ await first.return(undefined);
+ state.asksApproval = false;
+ state.chunks = [{ type: "done" }];
+ expect(await collect(HELLO)).toEqual([{ type: "done" }]);
+ });
+ });
+
describe("title generation", () => {
it("titles the note from the opening message, including the text parts of a multimodal one", async () => {
await collect([{ role: "user", content: "hello" }], { chatNoteId: "abc" });
diff --git a/packages/trilium-core/src/services/llm/chat.ts b/packages/trilium-core/src/services/llm/chat.ts
index 69dc422e53..57dc73dd33 100644
--- a/packages/trilium-core/src/services/llm/chat.ts
+++ b/packages/trilium-core/src/services/llm/chat.ts
@@ -14,6 +14,7 @@ import { safeExtractMessageAndStackFromError } from "../utils/index.js";
import { generateChatTitle } from "./chat_title.js";
import { getProvider, getProviderByType, getSearchProviderSetup, getSelectedModel, hasConfiguredProviders, type LlmProvider, type LlmProviderConfig } from "./index.js";
import { formatStreamError, streamToChunks } from "./stream.js";
+import { closeToolApprovals, openToolApprovals, type ToolApprovals } from "./tool_approval.js";
import { resolveToolRegistries } from "./tools/index.js";
/**
@@ -24,16 +25,31 @@ import { resolveToolRegistries } from "./tools/index.js";
* ends with a `done` chunk only when the turn completed — an errored one stops
* after its `error` chunk, so a caller that needs a terminator must add its own.
*
+ * Every tool call waits for the user: it is announced as a `tool_approval_request` chunk
+ * and answered through `answerToolApproval()`, keyed by `streamId`.
+ *
+ * @param streamId the id the client gave the turn, unique among the turns running.
* @param abortSignal stops the turn early: the provider aborts its completion and any tool
* call in progress, and the stream is left at the next chunk.
*/
export async function* runChat(
+ streamId: string,
messages: LlmMessage[],
requestConfig: LlmProviderConfig = {},
abortSignal?: AbortSignal
): AsyncGenerator<LlmStreamChunk> {
- // `webSearch` comes from the stored provider config only, never from the request.
- const config: LlmProviderConfig = { ...requestConfig, webSearch: getSearchProviderSetup(requestConfig.webSearchProviderId) };
+ const toolApprovals = openToolApprovals(streamId, abortSignal);
+ if (!toolApprovals) {
+ yield { type: "error", error: `Stream '${streamId}' is already running.` };
+ return;
+ }
+
+ // `webSearch` and `toolApprovals` come from here only, never from the request.
+ const config: LlmProviderConfig = {
+ ...requestConfig,
+ webSearch: getSearchProviderSetup(requestConfig.webSearchProviderId),
+ toolApprovals
+ };
try {
if (!hasConfiguredProviders()) {
yield { type: "error", error: "No LLM providers configured. Please add a provider in Options → AI / LLM." };
@@ -72,7 +88,7 @@ export async function* runChat(
? provider.chatChunks(messages, config, abortSignal)
: streamToChunks(provider.chat(messages, config, abortSignal), { model: modelDisplayName, provider: provider.name, pricing });
- for await (const chunk of chunks) {
+ for await (const chunk of withApprovalRequests(chunks, toolApprovals)) {
if (abortSignal?.aborted) {
// Naming the chat is downstream of this loop, so a stopped turn
// leaves the note on its timestamp. Said out loud, since from the
@@ -94,6 +110,56 @@ export async function* runChat(
const errorMessage = error instanceof Error ? error.message : "Unknown error";
getLog().error(`LLM chat stream failed: ${safeExtractMessageAndStackFromError(error)}`);
yield { type: "error", error: errorMessage };
+ } finally {
+ closeToolApprovals(streamId);
+ }
+}
+
+/**
+ * Yield the provider's chunks with a `tool_approval_request` for each call that starts
+ * waiting. A waiting call holds the provider's stream, so its request cannot come
+ * through it.
+ */
+async function* withApprovalRequests(
+ chunks: AsyncIterable<LlmStreamChunk>,
+ toolApprovals: ToolApprovals
+): AsyncGenerator<LlmStreamChunk> {
+ const requests: LlmStreamChunk[] = [];
+ let wake: (() => void) | undefined;
+ toolApprovals.onRequest = (request) => {
+ requests.push({ type: "tool_approval_request", ...request });
+ wake?.();
+ };
+
+ const iterator = chunks[Symbol.asyncIterator]();
+ let next = iterator.next();
+ try {
+ while (true) {
+ const request = requests.shift();
+ if (request) {
+ yield request;
+ continue;
+ }
+
+ const woken = new Promise<"woken">((resolve) => {
+ wake = () => resolve("woken");
+ });
+ const result = await Promise.race([ next, woken ]);
+ wake = undefined;
+ if (result === "woken") {
+ continue;
+ }
+ if (result.done) {
+ return;
+ }
+ next = iterator.next();
+ yield result.value;
+ }
+ } finally {
+ toolApprovals.onRequest = undefined;
+ // A consumer that stops early leaves `next` pending, and nothing waits on it any more.
+ next.catch(() => undefined);
+ void iterator.return?.()?.catch(() => undefined);
}
}
diff --git a/packages/trilium-core/src/services/llm/providers/anthropic.ts b/packages/trilium-core/src/services/llm/providers/anthropic.ts
index 735040e84f..7fb419d8ca 100644
--- a/packages/trilium-core/src/services/llm/providers/anthropic.ts
+++ b/packages/trilium-core/src/services/llm/providers/anthropic.ts
@@ -1,6 +1,6 @@
import { type AnthropicProvider as AnthropicSDKProvider,createAnthropic } from "@ai-sdk/anthropic";
import type { LlmMessage } from "@triliumnext/commons";
-import { type ModelMessage, stepCountIs, streamText, type SystemModelMessage, type ToolSet } from "ai";
+import { type ModelMessage, streamText, type SystemModelMessage, type ToolSet } from "ai";
import type { LlmProviderConfig, ModelInfo, StreamResult } from "../types.js";
import { BaseProvider, buildModelMessage, type RemoteModel, TELEMETRY_OFF } from "./base_provider.js";
@@ -158,12 +158,7 @@ export class AnthropicProvider extends BaseProvider {
}
};
- const tools = this.buildTools(config);
- if (Object.keys(tools).length > 0) {
- streamOptions.tools = tools;
- streamOptions.stopWhen = stepCountIs(5);
- streamOptions.toolChoice = "auto";
- }
+ this.addTools(streamOptions, config, 5);
return streamText(streamOptions);
}
diff --git a/packages/trilium-core/src/services/llm/providers/base_provider.spec.ts b/packages/trilium-core/src/services/llm/providers/base_provider.spec.ts
index c1856a15f3..d9aeaa2eb1 100644
--- a/packages/trilium-core/src/services/llm/providers/base_provider.spec.ts
+++ b/packages/trilium-core/src/services/llm/providers/base_provider.spec.ts
@@ -3,6 +3,7 @@ import { encodeUtf8 } from "../../../services/utils/binary.js";
import type { LanguageModel } from "ai";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TOOL_CALL_DECLINED_REASON, ToolApprovals } from "../tool_approval.js";
import type { LlmProviderConfig, ModelInfo } from "../types.js";
const { streamTextMock, generateTextMock, noteMetaMock, errorLogMock, beccaStub } = vi.hoisted(() => ({
@@ -617,6 +618,30 @@ describe("BaseProvider chat / pricing / models / title", () => {
expect(opts.toolChoice).toBe("auto");
expect(opts.stopWhen).toBeDefined();
expect(opts.maxOutputTokens).toBe(1234);
+ // Nothing to ask the user through, so the tools run unasked.
+ expect(opts.toolApproval).toBeUndefined();
+ });
+
+ it("holds every call the provider does not run itself until the user answers it", async () => {
+ const toolApprovals = new ToolApprovals();
+ const requests: unknown[] = [];
+ toolApprovals.onRequest = (request) => requests.push(request);
+ new TestProvider().chat([{ role: "user", content: "hi" }], { enableNoteTools: true, toolApprovals });
+ const { toolApproval } = streamTextMock.mock.calls[0][0] as any;
+ const call = (toolCallId: string, providerExecuted?: boolean) =>
+ toolApproval({ toolCall: { toolCallId, toolName: "fake_tool", input: { q: 1 }, providerExecuted } });
+
+ const approved = call("c1");
+ expect(requests).toEqual([{ toolCallId: "c1", toolName: "fake_tool", toolInput: { q: 1 } }]);
+ toolApprovals.answer("c1", true);
+ await expect(approved).resolves.toBe("approved");
+
+ const declined = call("c2");
+ toolApprovals.answer("c2", false);
+ await expect(declined).resolves.toEqual({ type: "denied", reason: TOOL_CALL_DECLINED_REASON });
+
+ await expect(call("c3", true)).resolves.toBe("not-applicable");
+ expect(requests).toHaveLength(2);
});
it("creates the model from config.model, falling back to the default", () => {
diff --git a/packages/trilium-core/src/services/llm/providers/base_provider.ts b/packages/trilium-core/src/services/llm/providers/base_provider.ts
index 43504e45f3..525f85360f 100644
--- a/packages/trilium-core/src/services/llm/providers/base_provider.ts
+++ b/packages/trilium-core/src/services/llm/providers/base_provider.ts
@@ -12,6 +12,7 @@ import { attachmentPlaceholder, resolveAttachmentPart } from "../attachment_cont
import { llmFetch } from "./fetch.js";
import { buildNoteHint } from "../note_hint.js";
import { buildSystemPrompt as composeSystemPrompt } from "../system_prompt.js";
+import { TOOL_CALL_DECLINED_REASON } from "../tool_approval.js";
import { allToolRegistries } from "../tools/index.js";
import type { LlmProvider, LlmProviderConfig, ModelInfo, ModelPricing, StreamResult } from "../types.js";
import { createReadWebPageTool, createWebSearchTool } from "../web_search.js";
@@ -440,14 +441,46 @@ export abstract class BaseProvider implements LlmProvider {
streamOptions.providerOptions = providerOptions;
}
+ this.addTools(streamOptions, config, 15);
+
+ return streamText(streamOptions);
+ }
+
+ /**
+ * Give a turn the tools of {@link buildTools}, letting it run up to `maxSteps` steps.
+ * With `config.toolApprovals`, every call the model makes waits for the user to answer it.
+ */
+ protected addTools(
+ streamOptions: Parameters<typeof streamText>[0],
+ config: LlmProviderConfig,
+ maxSteps: number
+ ): void {
const tools = this.buildTools(config);
- if (Object.keys(tools).length > 0) {
- streamOptions.tools = tools;
- streamOptions.stopWhen = stepCountIs(15);
- streamOptions.toolChoice = "auto";
+ if (Object.keys(tools).length === 0) {
+ return;
}
- return streamText(streamOptions);
+ streamOptions.tools = tools;
+ streamOptions.stopWhen = stepCountIs(maxSteps);
+ streamOptions.toolChoice = "auto";
+
+ const approvals = config.toolApprovals;
+ if (approvals) {
+ streamOptions.toolApproval = async ({ toolCall }) => {
+ // A tool the provider runs itself (such as Anthropic's web search) cannot be held.
+ if (toolCall.providerExecuted) {
+ return "not-applicable";
+ }
+ const approved = await approvals.request({
+ toolCallId: toolCall.toolCallId,
+ toolName: toolCall.toolName,
+ toolInput: toolCall.input as Record<string, unknown>
+ });
+ return approved
+ ? "approved"
+ : { type: "denied", reason: TOOL_CALL_DECLINED_REASON };
+ };
+ }
}
/** Provider-specific `providerOptions` for a chat turn, such as a reasoning effort. */
diff --git a/packages/trilium-core/src/services/llm/providers/google.ts b/packages/trilium-core/src/services/llm/providers/google.ts
index 0f0419975a..b8ce5b57c0 100644
--- a/packages/trilium-core/src/services/llm/providers/google.ts
+++ b/packages/trilium-core/src/services/llm/providers/google.ts
@@ -1,7 +1,7 @@
import { createGoogleGenerativeAI, type GoogleGenerativeAIProvider } from "@ai-sdk/google";
import type { LlmMessage } from "@triliumnext/commons";
import { getLog } from "../../../services/log.js";
-import { stepCountIs, streamText, type ToolSet } from "ai";
+import { streamText, type ToolSet } from "ai";
import type { LlmProviderConfig, StreamResult } from "../types.js";
import { BaseProvider, type RemoteModel, TELEMETRY_OFF } from "./base_provider.js";
@@ -117,12 +117,7 @@ export class GoogleProvider extends BaseProvider {
}
};
- const tools = this.buildTools(config);
- if (Object.keys(tools).length > 0) {
- streamOptions.tools = tools;
- streamOptions.stopWhen = stepCountIs(5);
- streamOptions.toolChoice = "auto";
- }
+ this.addTools(streamOptions, config, 5);
return streamText(streamOptions);
}
diff --git a/packages/trilium-core/src/services/llm/stream.spec.ts b/packages/trilium-core/src/services/llm/stream.spec.ts
index 9c4376e3c5..768cc21587 100644
--- a/packages/trilium-core/src/services/llm/stream.spec.ts
+++ b/packages/trilium-core/src/services/llm/stream.spec.ts
@@ -3,6 +3,7 @@ import { APICallError } from "ai";
import { describe, expect, it } from "vitest";
import { describeStreamError, formatStreamError, type StreamOptions, streamToChunks } from "./stream.js";
+import { TOOL_CALL_DECLINED_REASON } from "./tool_approval.js";
import type { ModelPricing, StreamResult } from "./types.js";
type ErrorChunk = Extract<LlmStreamChunk, { type: "error" }>;
@@ -188,6 +189,21 @@ describe("streamToChunks", () => {
expect(results[1]).toMatchObject({ result: JSON.stringify({ error: "boom" }), isError: true });
});
+ it("reports a call the user declined as a failed result, so its card settles", async () => {
+ const chunks = await collect(fakeResult(
+ [{ type: "tool-output-denied", toolCallId: "c1", toolName: "delete_note" }],
+ Promise.resolve({ inputTokens: 1, outputTokens: 1 })
+ ));
+
+ expect(chunks).toContainEqual({
+ type: "tool_result",
+ toolCallId: "c1",
+ toolName: "delete_note",
+ result: JSON.stringify({ error: TOOL_CALL_DECLINED_REASON }),
+ isError: true
+ });
+ });
+
it("emits citations only for url sources and ignores other source types", async () => {
const chunks = await collect(fakeResult(
[
diff --git a/packages/trilium-core/src/services/llm/stream.ts b/packages/trilium-core/src/services/llm/stream.ts
index 2f1dd12629..3318cbc94c 100644
--- a/packages/trilium-core/src/services/llm/stream.ts
+++ b/packages/trilium-core/src/services/llm/stream.ts
@@ -5,6 +5,7 @@
import { isToolErrorResult, type LlmErrorDetails, type LlmStreamChunk } from "@triliumnext/commons";
import { APICallError, type LanguageModelUsage } from "ai";
+import { TOOL_CALL_DECLINED_REASON } from "./tool_approval.js";
import type { ModelPricing, StreamResult } from "./types.js";
// Cache pricing assumes Anthropic's 5-min ephemeral rates (writes 1.25× input, reads 0.1× input).
@@ -176,6 +177,16 @@ export async function* streamToChunks(result: StreamResult, options: StreamOptio
break;
}
+ case "tool-output-denied":
+ yield {
+ type: "tool_result",
+ toolCallId: part.toolCallId,
+ toolName: part.toolName,
+ result: JSON.stringify({ error: TOOL_CALL_DECLINED_REASON }),
+ isError: true
+ };
+ break;
+
case "source":
// Citation from web search (only URL sources have url property)
if (part.sourceType === "url") {
diff --git a/packages/trilium-core/src/services/llm/tool_approval.spec.ts b/packages/trilium-core/src/services/llm/tool_approval.spec.ts
new file mode 100644
index 0000000000..41f74499f1
--- /dev/null
+++ b/packages/trilium-core/src/services/llm/tool_approval.spec.ts
@@ -0,0 +1,132 @@
+import type { LlmStreamChunk } from "@triliumnext/commons";
+import { type LanguageModel, simulateReadableStream, tool, type ToolSet } from "ai";
+import { MockLanguageModelV4 } from "ai/test";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+
+import { BaseProvider } from "./providers/base_provider.js";
+import { streamToChunks } from "./stream.js";
+import { TOOL_CALL_DECLINED_REASON, ToolApprovals } from "./tool_approval.js";
+
+const USAGE = {
+ inputTokens: { total: 1, noCache: 1, cacheRead: 0, cacheWrite: 0 },
+ outputTokens: { total: 1, text: 1, reasoning: 0 }
+};
+
+/** A model that calls `create_note` once, then answers with text. */
+function modelCallingTool() {
+ return new MockLanguageModelV4({
+ doStream: [
+ {
+ stream: simulateReadableStream({
+ chunks: [
+ { type: "tool-call", toolCallId: "c1", toolName: "create_note", input: JSON.stringify({ title: "New" }) },
+ { type: "finish", usage: USAGE, finishReason: { unified: "tool-calls", raw: undefined } }
+ ]
+ })
+ },
+ {
+ stream: simulateReadableStream({
+ chunks: [
+ { type: "text-start", id: "t1" },
+ { type: "text-delta", id: "t1", delta: "Done." },
+ { type: "text-end", id: "t1" },
+ { type: "finish", usage: USAGE, finishReason: { unified: "stop", raw: undefined } }
+ ]
+ })
+ }
+ ]
+ });
+}
+
+class ScriptedProvider extends BaseProvider {
+ name = "scripted";
+ protected defaultModel = "mock";
+ protected titleModel = "mock";
+ readonly execute = vi.fn((_input: unknown) => ({ noteId: "n1" }));
+
+ constructor(private readonly model: MockLanguageModelV4) {
+ super("key");
+ }
+
+ protected createModel(): LanguageModel {
+ return this.model;
+ }
+
+ protected override buildTools(): ToolSet {
+ return {
+ create_note: tool({
+ description: "Create a note",
+ inputSchema: z.object({ title: z.string() }),
+ execute: this.execute
+ })
+ };
+ }
+}
+
+/**
+ * Run a turn through the AI SDK, answering each approval request with `approve` as soon as it
+ * is made, as the user would from the chat.
+ */
+async function runTurn(approve: boolean) {
+ const model = modelCallingTool();
+ const provider = new ScriptedProvider(model);
+ const toolApprovals = new ToolApprovals();
+ const requests: unknown[] = [];
+ toolApprovals.onRequest = (request) => {
+ requests.push(request);
+ queueMicrotask(() => toolApprovals.answer(request.toolCallId, approve));
+ };
+
+ const chunks: LlmStreamChunk[] = [];
+ for await (const chunk of streamToChunks(provider.chat([ { role: "user", content: "make a note" } ], { toolApprovals }))) {
+ chunks.push(chunk);
+ }
+ return { chunks, requests, execute: provider.execute, model };
+}
+
+describe("tool approval through the AI SDK", () => {
+ it("runs an approved call and carries on with the turn", async () => {
+ const { chunks, requests, execute, model } = await runTurn(true);
+
+ expect(requests).toEqual([ { toolCallId: "c1", toolName: "create_note", toolInput: { title: "New" } } ]);
+ expect(execute).toHaveBeenCalledOnce();
+ expect(chunks).toContainEqual(expect.objectContaining({ type: "tool_result", toolCallId: "c1", isError: false }));
+ expect(chunks).toContainEqual({ type: "text", content: "Done." });
+ expect(model.doStreamCalls).toHaveLength(2);
+ });
+
+ it("never runs a declined call, and tells the model why before it carries on", async () => {
+ const { chunks, execute, model } = await runTurn(false);
+
+ expect(execute).not.toHaveBeenCalled();
+ expect(chunks).toContainEqual({
+ type: "tool_result",
+ toolCallId: "c1",
+ toolName: "create_note",
+ result: JSON.stringify({ error: TOOL_CALL_DECLINED_REASON }),
+ isError: true
+ });
+ expect(chunks).toContainEqual({ type: "text", content: "Done." });
+
+ const toolMessage = model.doStreamCalls[1]?.prompt.find((message) => message.role === "tool");
+ expect(JSON.stringify(toolMessage)).toContain(TOOL_CALL_DECLINED_REASON);
+ });
+});
+
+describe("ToolApprovals", () => {
+ it("declines what waits when the turn is stopped or closed, and every call once stopped", async () => {
+ const controller = new AbortController();
+ const approvals = new ToolApprovals(controller.signal);
+ const stopped = approvals.request({ toolCallId: "c1", toolName: "t", toolInput: {} });
+ controller.abort();
+ await expect(stopped).resolves.toBe(false);
+ await expect(approvals.request({ toolCallId: "c2", toolName: "t", toolInput: {} })).resolves.toBe(false);
+
+ const open = new ToolApprovals();
+ const closed = open.request({ toolCallId: "c3", toolName: "t", toolInput: {} });
+ open.declineAll();
+ await expect(closed).resolves.toBe(false);
+ expect(open.answer("c3", true)).toBe(false);
+ });
+});
diff --git a/packages/trilium-core/src/services/llm/tool_approval.ts b/packages/trilium-core/src/services/llm/tool_approval.ts
new file mode 100644
index 0000000000..fe1bd04cd5
--- /dev/null
+++ b/packages/trilium-core/src/services/llm/tool_approval.ts
@@ -0,0 +1,96 @@
+/**
+ * The user's approval of the tool calls a chat turn makes.
+ *
+ * A turn holds its tool calls until the user answers them: `runChat()` opens a
+ * {@link ToolApprovals} under the turn's stream id, the provider asks it about every
+ * call through the AI SDK's `toolApproval` option, and the answer arrives through
+ * `POST /api/llm-chat/tool-approval`, which looks the turn up by that id. Waiting
+ * inside the turn keeps the conversation history free of tool calls, which the
+ * client does not send back.
+ */
+
+import type { LlmToolApprovalRequest } from "@triliumnext/commons";
+
+/** The reason the model is given for a call the user declined. */
+export const TOOL_CALL_DECLINED_REASON = "The user declined this tool call.";
+
+/** The tool calls of one turn that wait for the user's answer. */
+export class ToolApprovals {
+ private readonly pending = new Map<string, (approved: boolean) => void>();
+ /** Called with every request, so the turn can pass it on to the client. */
+ onRequest?: (request: LlmToolApprovalRequest) => void;
+
+ constructor(private readonly abortSignal?: AbortSignal) {}
+
+ /**
+ * Ask the user about a tool call. Resolves to whether it was approved; a turn that
+ * is stopped, or ends, before the user answers declines the call.
+ */
+ request(request: LlmToolApprovalRequest): Promise<boolean> {
+ if (this.abortSignal?.aborted) {
+ return Promise.resolve(false);
+ }
+
+ return new Promise((resolve) => {
+ const settle = (approved: boolean) => {
+ this.pending.delete(request.toolCallId);
+ this.abortSignal?.removeEventListener("abort", onAbort);
+ resolve(approved);
+ };
+ const onAbort = () => settle(false);
+ this.abortSignal?.addEventListener("abort", onAbort, { once: true });
+ this.pending.set(request.toolCallId, settle);
+ this.onRequest?.(request);
+ });
+ }
+
+ /** Settle a pending call. Returns `false` when no call with that id is waiting. */
+ answer(toolCallId: string, approved: boolean): boolean {
+ const settle = this.pending.get(toolCallId);
+ settle?.(approved);
+ return !!settle;
+ }
+
+ /** Decline every call that still waits. */
+ declineAll(): void {
+ for (const settle of [ ...this.pending.values() ]) {
+ settle(false);
+ }
+ }
+}
+
+const openApprovals = new Map<string, ToolApprovals>();
+
+/**
+ * Open the approvals of a turn under its stream id. Returns `undefined` when a turn
+ * with that id is already running.
+ */
+export function openToolApprovals(
+ streamId: string,
+ abortSignal?: AbortSignal
+): ToolApprovals | undefined {
+ if (openApprovals.has(streamId)) {
+ return undefined;
+ }
+ const approvals = new ToolApprovals(abortSignal);
+ openApprovals.set(streamId, approvals);
+ return approvals;
+}
+
+/** Close the approvals of a finished turn, declining whatever still waits. */
+export function closeToolApprovals(streamId: string): void {
+ openApprovals.get(streamId)?.declineAll();
+ openApprovals.delete(streamId);
+}
+
+/**
+ * Pass on the user's answer to a tool call. Returns `false` when the turn has ended or
+ * the call was already answered.
+ */
+export function answerToolApproval(
+ streamId: string,
+ toolCallId: string,
+ approved: boolean
+): boolean {
+ return openApprovals.get(streamId)?.answer(toolCallId, approved) ?? false;
+}
diff --git a/packages/trilium-core/src/services/llm/types.ts b/packages/trilium-core/src/services/llm/types.ts
index d62179f829..ffdfad3761 100644
--- a/packages/trilium-core/src/services/llm/types.ts
+++ b/packages/trilium-core/src/services/llm/types.ts
@@ -7,6 +7,7 @@
import type { LlmAttachmentKind, LlmChatConfig, LlmMessage, LlmReasoningEffort, LlmStreamChunk } from "@triliumnext/commons";
import type { streamText } from "ai";
+import type { ToolApprovals } from "./tool_approval.js";
import type { WebSearchSetup } from "./web_search.js";
/**
@@ -20,6 +21,11 @@ export interface LlmProviderConfig extends LlmChatConfig {
* `runChat()`. When set, web search goes through it instead of the model's built-in search.
*/
webSearch?: WebSearchSetup;
+ /**
+ * Where the turn asks the user about each tool call, set by `runChat()`. Absent, the
+ * tools run unasked.
+ */
+ toolApprovals?: ToolApprovals;
}
/**