Skip to content

Build your personal knowledge base with Trilium Notes

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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));
}