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
/**
* Decides every tool call Codex makes.
*
* Codex's `read-only` mode confines writes and the network, not reads: its
* shell and its image viewer (`view_image`, which opens any file) run without
* asking permission, and its web search (`webrun`) is on by default. More tools
* arrive with Codex's releases (apps, a browser), and the user brings their own
* Codex, so a list of what to switch off cannot keep up.
*
* Codex runs `PreToolUse` hooks from `<CODEX_HOME>/hooks.json` before every tool
* call, built-in and MCP alike, so Trilium writes one there that posts each
* call to its loopback listener (`getAcpHookEndpointUrl`) with `curl`, and
* {@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";
import { type BuiltInToolDisplay, NOTE_TOOLS_MCP_SERVER_NAME } from "./acp_agent.js";
import { buildHookCommand, stringsIn } from "./acp_hook.js";
import { type HostLookup, isPublicHttpUrl } from "./public_url.js";
/** What the hook prints: no decision leaves the call to Codex, a `deny` stops it. */
export interface CodexHookAnswer {
hookSpecificOutput?: {
hookEventName: "PreToolUse";
permissionDecision: "deny";
permissionDecisionReason: string;
};
}
/** The name Codex gives its web search in hook events. */
const WEB_TOOL = "webrun";
/** `webrun` arguments that tune every operation rather than name one. */
const WEBRUN_OPTIONS = new Set([ "response_length" ]);
/** How `webrun` answers a call it could not run, in place of results. */
const WEBRUN_NO_RESPONSE = "Found no tool response.";
/** `<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;
const NOTE_TOOLS_ONLY = "Trilium does not allow this tool. Use Trilium's note tools to read, search and edit the user's notes instead.";
const WEB_SEARCH_OFF = "Web search is turned off for this chat.";
const PRIVATE_ADDRESS = "Trilium does not allow opening local or private addresses.";
const UNKNOWN_RESULT = "Trilium can only open search results this chat's searches returned. Open the page by its URL instead.";
/** What the hook knows of the chat turn running in a session (the event's `session_id`, the ACP session id). */
export interface CodexTurns {
/** The turn's configuration. */
configOf(sessionId: string): LlmProviderConfig | undefined;
/** The URL of a search result the turn's web searches returned, by its id (`turn1search0`). */
urlOf(sessionId: string, ref: string): string | undefined;
}
/**
* The answer to one `PreToolUse` call: Trilium's note tools pass, and the web
* search passes in a chat that allows it when every URL it opens is on the
* public internet. A page opened by a search result's id is checked by that
* result's URL, and an id the turn's searches never returned is refused, as
* its destination cannot be checked. Everything else is denied.
*/
export async function decideCodexToolCall(payload: unknown, turns: CodexTurns, lookup?: HostLookup): Promise<CodexHookAnswer> {
const event = payload as { tool_name?: unknown; tool_input?: unknown; session_id?: unknown } | null;
const toolName = typeof event?.tool_name === "string" ? event.tool_name : "";
if (toolName.startsWith(`mcp__${NOTE_TOOLS_MCP_SERVER_NAME}__`)) {
return {};
}
if (toolName !== WEB_TOOL) {
return deny(NOTE_TOOLS_ONLY);
}
const sessionId = typeof event?.session_id === "string" ? event.session_id : undefined;
if (sessionId === undefined || turns.configOf(sessionId)?.enableWebSearch !== true) {
return deny(WEB_SEARCH_OFF);
}
const isUrl = (value: string) => /^https?:\/\//i.test(value);
const opened = (event?.tool_input as { open?: unknown } | null | undefined)?.open;
const urls = stringsIn(event?.tool_input).filter(isUrl);
for (const ref of stringsIn(opened).filter(value => !isUrl(value))) {
const url = turns.urlOf(sessionId, ref);
if (url === undefined) {
return deny(UNKNOWN_RESULT);
}
urls.push(url);
}
const allPublic = await Promise.all(urls.map(url => isPublicHttpUrl(url, lookup)));
return allPublic.every(Boolean) ? {} : deny(PRIVATE_ADDRESS);
}
/**
* 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 };
}
/**
* How the chat shows a `webrun` call. `webrun` runs several operations —
* `search_query` (`[{ q }]`), `open` (`[{ ref_id }]`, a URL or the id of an
* earlier result, which `urlOf` resolves), and others such as `weather`
* (`[{ location }]`) — which the adapter reports as a web search with an empty
* query unless it is a search. A call that only opens a page is the chat's
* `read_web_page`; the rest are `web_search`, with the query or operation.
*/
export function describeWebrunInput(toolInput: unknown, urlOf: (ref: string) => string | undefined = () => undefined): BuiltInToolDisplay {
const operations = Object.entries(toolInput && typeof toolInput === "object" ? toolInput : {})
.filter(([ operation ]) => !WEBRUN_OPTIONS.has(operation));
if (operations.length === 1 && operations[0][0] === "open") {
const ref = stringsIn(operations[0][1])[0];
const url = ref && (/^https?:\/\//i.test(ref) ? ref : urlOf(ref));
return { toolName: "read_web_page", toolInput: url ? { url } : {} };
}
const parts = operations.map(([ operation, value ]) => {
const values = stringsIn(value).join(", ");
return operation === "search_query" ? values : `${operation}: ${values}`;
}).filter(Boolean);
return { toolName: "web_search", toolInput: parts.length > 0 ? { query: parts.join("; ") } : {} };
}
/**
* The `webrun` call a `PostToolUse` event reports as failed although Codex
* reported it done: its response then says so in place of results, as for a
* `weather` call whose location it could not read. Undefined for any other
* event.
*/
export function webrunFailure(payload: unknown): { sessionId: string; toolCallId: string; reason: string } | undefined {
const event = payload as { hook_event_name?: unknown; tool_name?: unknown; session_id?: unknown; tool_use_id?: unknown; tool_response?: unknown } | null;
if (event?.hook_event_name !== "PostToolUse" || event.tool_name !== WEB_TOOL
|| typeof event.session_id !== "string" || typeof event.tool_use_id !== "string") {
return undefined;
}
const reason = stringsIn(event.tool_response).find(text => text.startsWith(WEBRUN_NO_RESPONSE));
return reason ? { sessionId: event.session_id, toolCallId: event.tool_use_id, reason } : undefined;
}
/**
* 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));
}
/**
* Antigravity's `curl` command, failing closed: Codex blocks a call only on
* exit code 2, so any failure (Trilium unreachable, an error response, the
* time limit) becomes one. `||` reads the same under `sh -c` and `cmd /c`.
*/
export function buildCodexHookCommand(curl: string, hookUrl: string): string {
return `${buildHookCommand(curl, hookUrl)} || exit 2`;
}
function deny(reason: string): CodexHookAnswer {
return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } };
}