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): turn Codex's citation markers into Trilium citations
Elian Doranf962cfc3e249
diff --git a/apps/server/src/services/llm/providers/codex_agent.spec.ts b/apps/server/src/services/llm/providers/codex_agent.spec.tsindex 6954e84d87..38a4398a6f 100644--- a/apps/server/src/services/llm/providers/codex_agent.spec.ts+++ b/apps/server/src/services/llm/providers/codex_agent.spec.ts@@ -307,7 +307,7 @@ describe("CodexAgentProvider note tools", () => {});describe("CodexAgentProvider web search", () => {- it("lets the web search through the hook only in a chat that allows it, and shows it as a web search", async () => {+ it("lets the web search through the hook only in a chat that allows it, and shows it as a web search with its sources", async () => {const decisions: unknown[] = [];FakeAcpClient.onPrompt = async client => {const decide = getAcpHookEndpointUrlMock.mock.calls.at(-1)?.[1];@@ -316,6 +316,11 @@ describe("CodexAgentProvider web search", () => {update({ sessionUpdate: "tool_call", toolCallId: "search-1", kind: "search", title: "Web search", status: "in_progress", rawInput: { type: "webSearch", query: "" } });// codex-acp 1.13.1 reports a finished search with no content, only its final title.update({ sessionUpdate: "tool_call_update", toolCallId: "search-1", title: "Web search: weather Sibiu", status: "completed", rawInput: { type: "webSearch", query: "weather Sibiu" } });+ // The search's results, as the PostToolUse hook posts them; the marker below cites one of them and one it never returned.+ await decide?.({+ hook_event_name: "PostToolUse", session_id: "sess-1", tool_name: "webrun",+ tool_response: [ { type: "input_text", text: "Vremea \u00een Sibiu (https://www.celsium.ro/vremea-sibiu)\n\uE200cite\uE202turn3search2\uE201 [wordlim: 200] Crawled: today" } ]+ });// A citation marker, split across chunks as a stream can split it.for (const text of [ "Cloudy, 12\u00b0C. \uE200cite\uE202turn3se", "arch2\uE202turn3search0\uE201", " Low chance of rain." ]) {update({ sessionUpdate: "agent_message_chunk", content: { type: "text", text } });@@ -334,13 +339,17 @@ describe("CodexAgentProvider web search", () => {// A finished call the chat would otherwise show as still running.expect(searching).toContainEqual({ type: "tool_result", toolCallId: "search-1", toolName: "web_search", result: "Web search: weather Sibiu", isError: false });expect(searching.map(c => (c.type === "text" ? c.content : "")).join("")).toBe("Cloudy, 12\u00b0C. Low chance of rain.");+ // The marker becomes a Trilium citation for the result the search returned.+ expect(searching.filter(c => c.type === "citation")).toEqual([+ { type: "citation", citation: { title: "Vremea \u00een Sibiu", url: "https://www.celsium.ro/vremea-sibiu" } }+ ]);});});describe("CitationStripper", () => {const strip = (...chunks: string[]) => {const stripper = new CitationStripper();- return chunks.map(chunk => stripper.push(chunk));+ return chunks.map(chunk => stripper.push(chunk).text);};it("removes whole and split markers, holding back only what a marker might still need", () => {@@ -350,6 +359,11 @@ describe("CitationStripper", () => {expect(strip("A \uE200cite\uE202turn0")).toEqual([ "A " ]);});+ it("reports the search results a marker cites, and nothing for another kind of marker", () => {+ expect(new CitationStripper().push("A \uE200cite\uE202turn1search0\uE202turn1search3\uE201 B \uE200entity\uE202x\uE201"))+ .toEqual({ text: "A B ", refs: [ "turn1search0", "turn1search3" ] });+ });+it("lets an opening through once it has run longer than any marker", () => {expect(strip("A \uE200", "x".repeat(250))).toEqual([ "A ", "x".repeat(250) ]);});diff --git a/apps/server/src/services/llm/providers/codex_agent.ts b/apps/server/src/services/llm/providers/codex_agent.tsindex 5cd983c1f2..932373869a 100644--- a/apps/server/src/services/llm/providers/codex_agent.ts+++ b/apps/server/src/services/llm/providers/codex_agent.ts@@ -15,7 +15,7 @@* calls to Trilium's note tools.*/-import { LLM_REASONING_EFFORTS, type LlmMessage, type LlmReasoningEffort, type LlmStreamChunk } from "@triliumnext/commons";+import { LLM_REASONING_EFFORTS, type LlmCitation, type LlmMessage, type LlmReasoningEffort, type LlmStreamChunk } from "@triliumnext/commons";import type { LlmProviderConfig, ModelInfo } from "@triliumnext/core/src/services/llm/types.js";import path from "path";@@ -23,9 +23,9 @@ import dataDirs from "../../data_dir.js";import { AcpAgentProvider, type AcpLaunchSpec, type AcpModel, type AcpNewSessionParams, type AcpPermissionOutcome, type AcpPermissionRequest, type AcpSessionModelState, type AcpToolCallUpdate, type BuiltInToolDisplay, denyPermission, describeError, NOTE_TOOLS_MCP_SERVER_NAME } from "./acp_agent.js";import { type AcpClient, AcpError } from "./acp_client.js";import { getAcpHookEndpointUrl } from "./acp_mcp_endpoint.js";-import { resolveCurlPath } from "./antigravity_hook.js";+import { buildHookCommand, resolveCurlPath } from "./antigravity_hook.js";import { resolveCodexAcpScript, resolveCodexBinaryPath } from "./codex_binary.js";-import { buildCodexHookCommand, decideCodexToolCall, writeCodexHooks } from "./codex_hook.js";+import { buildCodexHookCommand, type CodexHookAnswer, codexSearchSources, decideCodexToolCall, writeCodexHooks } from "./codex_hook.js";/** The model id that leaves the session on the model Codex picks. */const DEFAULT_MODEL_ID = "default";@@ -66,6 +66,13 @@ const VARIANT_NAME = /^(.+?) \([^)]+\)$/;*/let catalog: { efforts: Map<string, LlmReasoningEffort[]>; titleModel?: string } = { efforts: new Map() };+/**+ * The sources each chat turn's web searches returned, by the id the model cites+ * them with, keyed by the turn's configuration: the object the pool attaches to+ * the turn's session, which the hook finds by session id.+ */+const sourcesByTurn = new WeakMap<LlmProviderConfig, Map<string, LlmCitation>>();+export class CodexAgentProvider extends AcpAgentProvider {name = "codex-agent";protected readonly logLabel = "Codex Agent provider";@@ -90,10 +97,10 @@ export class CodexAgentProvider extends AcpAgentProvider {const [ codex, curl, hookUrl ] = await Promise.all([resolveCodexBinaryPath(),resolveCurlPath(),- getAcpHookEndpointUrl("codex", payload => decideCodexToolCall(payload, sessionId => this.turnConfigOf(sessionId)))+ getAcpHookEndpointUrl("codex", payload => this.answerHook(payload))]);const home = agentHome();- writeCodexHooks(home, buildCodexHookCommand(curl, hookUrl));+ writeCodexHooks(home, buildCodexHookCommand(curl, hookUrl), buildHookCommand(curl, hookUrl));return {binary: resolveCodexAcpScript(),args: [],@@ -162,11 +169,37 @@ export class CodexAgentProvider extends AcpAgentProvider {yield chunk;continue;}- const text = citations.push(chunk.content);+ const { text, refs } = citations.push(chunk.content);if (text) {yield { ...chunk, content: text };}+ for (const ref of refs) {+ const citation = sourcesByTurn.get(config)?.get(ref);+ if (citation) {+ yield { type: "citation", citation };+ }+ }+ }+ }++ /**+ * Answer the hook: decide a tool call before it runs, and after a web search+ * remember its sources for the turn, which the citations in the reply name.+ */+ private answerHook(payload: unknown): Promise<CodexHookAnswer> | CodexHookAnswer {+ const search = codexSearchSources(payload);+ if (!search) {+ return decideCodexToolCall(payload, sessionId => this.turnConfigOf(sessionId));+ }+ const config = this.turnConfigOf(search.sessionId);+ if (config) {+ const known = sourcesByTurn.get(config) ?? new Map<string, LlmCitation>();+ for (const [ ref, citation ] of search.sources) {+ known.set(ref, citation);+ }+ sourcesByTurn.set(config, known);}+ return {};}protected describeFailure(error: unknown): string {@@ -319,34 +352,42 @@ function isSignInRequired(error: unknown): boolean {return error instanceof AcpError && error.code === -32000 && /authentication required/i.test(error.message);}-/** A citation marker opens with U+E200 and closes with U+E201, private-use characters. */-const MARKER_START = "";-const COMPLETE_MARKER = /[^]*/g;+/** A citation marker opens with U+E200, separates its parts with U+E202 and closes with U+E201, private-use characters. */+const MARKER_START = "\uE200";+const MARKER_SEPARATOR = "\uE202";+const COMPLETE_MARKER = /\uE200[^\uE201]*\uE201/g;/** Longer than any citation marker; an opening held back past it was no marker. */const MAX_MARKER_LENGTH = 200;/*** Removes the citation markers OpenAI's models write after a web search,- * `U+E200 cite U+E202 turn3search2 U+E201`, from streamed text. Codex's own- * interface turns them into links to the search results, which the adapter- * never passes on, so the chat would show them as `citeturn3search2`. A+ * `U+E200 cite U+E202 turn3search2 U+E201`, from streamed text, and reports the+ * search results they cite, which {@link CodexAgentProvider.chatChunks} turns into+ * Trilium citations. Left in, the chat would show them as `citeturn3search2`. A* marker can span chunks, so text from an unclosed one is held back until it* closes, and dropped if it never does.*/export class CitationStripper {private pending = "";- /** The text of `chunk` that is safe to show now. */- push(chunk: string): string {- let text = (this.pending + chunk).replace(COMPLETE_MARKER, "");+ /** The text of `chunk` that is safe to show now, and the search results the removed markers cite. */+ push(chunk: string): { text: string; refs: string[] } {+ const refs: string[] = [];+ let text = (this.pending + chunk).replace(COMPLETE_MARKER, marker => {+ const [ kind, ...ids ] = marker.slice(1, -1).split(MARKER_SEPARATOR);+ if (kind === "cite") {+ refs.push(...ids);+ }+ return "";+ });let open = text.indexOf(MARKER_START);if (open >= 0 && text.length - open > MAX_MARKER_LENGTH) {text = text.replaceAll(MARKER_START, "");open = -1;}this.pending = open >= 0 ? text.slice(open) : "";- return open >= 0 ? text.slice(0, open) : text;+ return { text: open >= 0 ? text.slice(0, open) : text, refs };}}diff --git a/apps/server/src/services/llm/providers/codex_hook.spec.ts b/apps/server/src/services/llm/providers/codex_hook.spec.tsindex 9c87ebfbdb..bda70f1f4d 100644--- a/apps/server/src/services/llm/providers/codex_hook.spec.ts+++ b/apps/server/src/services/llm/providers/codex_hook.spec.ts@@ -5,7 +5,7 @@ import path from "path";import { describe, expect, it } from "vitest";import { resolveCurlPath } from "./antigravity_hook.js";-import { buildCodexHookCommand, decideCodexToolCall, writeCodexHooks } from "./codex_hook.js";+import { buildCodexHookCommand, codexSearchSources, decideCodexToolCall, writeCodexHooks } from "./codex_hook.js";/** `PreToolUse` events as Codex 0.146.0 and 0.156.1 send them, less the session bookkeeping. */const EVENTS = {@@ -46,12 +46,15 @@ describe("decideCodexToolCall", () => {});describe("Codex hook", () => {- it("writes a hook for every tool call to hooks.json in Codex's home", () => {+ it("writes a hook before and after every tool call to hooks.json in Codex's home", () => {const home = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "trilium-codex-hook-")), "home");try {- writeCodexHooks(home, "run-the-hook");+ writeCodexHooks(home, "before", "after");expect(JSON.parse(fs.readFileSync(path.join(home, "hooks.json"), "utf8"))).toEqual({- hooks: { PreToolUse: [ { matcher: ".*", hooks: [ { type: "command", command: "run-the-hook", timeout: 10 } ] } ] }+ hooks: {+ PreToolUse: [ { matcher: ".*", hooks: [ { type: "command", command: "before", timeout: 10 } ] } ],+ PostToolUse: [ { matcher: ".*", hooks: [ { type: "command", command: "after", timeout: 10 } ] } ]+ }});} finally {fs.rmSync(path.dirname(home), { recursive: true, force: true });@@ -72,3 +75,32 @@ describe("Codex hook", () => {expect(exitCode).toBe(2);});});++describe("codexSearchSources", () => {+ /** The start of a `webrun` response as Codex 0.156.1 sent it after a search. */+ const RESPONSE = [ { type: "input_text", text: [+ "Vremea în Sibiu pe 26 septembrie 2026 (Prognoza) (https://www.celsium.ro/vremea-sibiu/2026-09-26)",+ "\uE200cite\uE202turn1search0\uE201 [wordlim: 200] Crawled: 2 days ago; # Vremea în Sibiu",+ "some page text (https://example.com/not-a-header)",+ "Sibiu (https://en.wikipedia.org/wiki/Sibiu_(city))",+ "\uE200cite\uE202turn1search13\uE201 [wordlim: 200] Crawled: 4 months ago; Sibiu"+ ].join("\n") } ];+ const post = (extra: object) => ({ hook_event_name: "PostToolUse", session_id: "sess-1", tool_name: "webrun", tool_response: RESPONSE, ...extra });++ it("maps each search result's citation id to its title and URL", () => {+ expect(codexSearchSources(post({}))).toEqual({+ sessionId: "sess-1",+ sources: new Map([+ [ "turn1search0", { title: "Vremea în Sibiu pe 26 septembrie 2026 (Prognoza)", url: "https://www.celsium.ro/vremea-sibiu/2026-09-26" } ],+ [ "turn1search13", { title: "Sibiu", url: "https://en.wikipedia.org/wiki/Sibiu_(city)" } ]+ ])+ });+ });++ it("reads only a finished web search", () => {+ expect(codexSearchSources(post({ hook_event_name: "PreToolUse" }))).toBeUndefined();+ expect(codexSearchSources(post({ tool_name: "mcp__trilium__read_note" }))).toBeUndefined();+ expect(codexSearchSources(post({ session_id: undefined }))).toBeUndefined();+ expect(codexSearchSources(null)).toBeUndefined();+ });+});diff --git a/apps/server/src/services/llm/providers/codex_hook.ts b/apps/server/src/services/llm/providers/codex_hook.tsindex 34eed77938..10d7869fd5 100644--- a/apps/server/src/services/llm/providers/codex_hook.ts+++ b/apps/server/src/services/llm/providers/codex_hook.ts@@ -13,8 +13,12 @@* {@link decideCodexToolCall} answers from an allow-list. Codex lets a call* through when its hook fails with any exit code but 2, so the hook command* turns a failed `curl` into exit 2.+ *+ * A `PostToolUse` hook posts each finished call too, so Trilium can read the+ * sources out of a web search (see {@link codexSearchSources}).*/+import type { LlmCitation } from "@triliumnext/commons";import type { LlmProviderConfig } from "@triliumnext/core/src/services/llm/types.js";import { mkdirSync, writeFileSync } from "fs";import path from "path";@@ -35,6 +39,9 @@ export interface CodexHookAnswer {/** The name Codex gives its web search in hook events. */const WEB_TOOL = "webrun";+/** `<title> (<url>)` and, on the next line, the result's citation marker, `U+E200 cite U+E202 <id> U+E201`. */+const SEARCH_RESULT_HEADER = /^(.*) \((https?:\/\/\S+)\)\n\uE200cite\uE202([^\uE201\uE202]+)\uE201/gm;+/** How long Codex waits for the hook, in seconds; `curl` (see `buildHookCommand`) gives up first. */const HOOK_TIMEOUT_S = 10;@@ -70,14 +77,35 @@ export async function decideCodexToolCall(return allPublic.every(Boolean) ? {} : deny(PRIVATE_ADDRESS);}-/** Write the hook to `<home>/hooks.json`, replacing what an earlier run wrote. */-export function writeCodexHooks(home: string, command: string): void {- mkdirSync(home, { recursive: true });- const hooks = {- hooks: {- PreToolUse: [ { matcher: ".*", hooks: [ { type: "command", command, timeout: HOOK_TIMEOUT_S } ] } ]+/**+ * The sources a web search returned, by the id the model cites them with+ * (`turn1search0`), from a `PostToolUse` event for `webrun`; undefined for any+ * other event. Each result in the tool's response opens with a line+ * `<title> (<url>)` followed by the result's citation marker.+ */+export function codexSearchSources(payload: unknown): { sessionId: string; sources: Map<string, LlmCitation> } | undefined {+ const event = payload as { hook_event_name?: unknown; tool_name?: unknown; tool_response?: unknown; session_id?: unknown } | null;+ if (event?.hook_event_name !== "PostToolUse" || event.tool_name !== WEB_TOOL || typeof event.session_id !== "string") {+ return undefined;+ }+ const sources = new Map<string, LlmCitation>();+ for (const text of stringsIn(event.tool_response)) {+ for (const [ , title, url, ref ] of text.matchAll(SEARCH_RESULT_HEADER)) {+ sources.set(ref, { title, url });}- };+ }+ return { sessionId: event.session_id, sources };+}++/**+ * Write the hooks to `<home>/hooks.json`, replacing what an earlier run wrote:+ * `preCommand` before every tool call, `postCommand` after, which reads the+ * sources out of a web search (see {@link codexSearchSources}).+ */+export function writeCodexHooks(home: string, preCommand: string, postCommand: string): void {+ mkdirSync(home, { recursive: true });+ const hook = (command: string) => [ { matcher: ".*", hooks: [ { type: "command", command, timeout: HOOK_TIMEOUT_S } ] } ];+ const hooks = { hooks: { PreToolUse: hook(preCommand), PostToolUse: hook(postCommand) } };writeFileSync(path.join(home, "hooks.json"), JSON.stringify(hooks, null, 2));}