Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

10.9 KB
Raw Blame
import { statSync } from 'node:fs';
import { dirname, join, resolve } from 'node:path';
import type { McpServerStdio } from '@agentclientprotocol/sdk';
import { asRecord, stringField } from '@inkeep/open-knowledge-core/acp/tool-call-input';
import { tracedMkdir, tracedRm, tracedWriteFile } from '../fs-traced.ts';
import { resolveOnPath } from '../git-preflight.ts';
import { runBrowserRelay } from './browser-relay.ts';
import { mergedEnv, type ResolvedLaunch } from './launch.ts';
import { isMintedThreadId } from './thread-persistence.ts';

export const AGENT_BROWSER_MCP_PACKAGE = '@playwright/[email protected]';

const AGENT_BROWSER_SERVER_NAME = 'ok-browser';

const CODEX_AGENT_ID = 'codex-acp';

const BROWSER_AGENT_IDS: ReadonlySet<string> = new Set(['claude-acp', CODEX_AGENT_ID]);

const BROWSER_TOOL_NAME = /^browser_[a-z_]+$/;

const BROWSER_TOOL_TITLE = /^(?:mcp[^a-z0-9]+)?ok[^a-z0-9]?browser[^a-z0-9]+(browser_[a-z_]+)$/;

const CLAUDE_MCP_TOOL = /^mcp__(.+?)__(.+)$/;

const CODEX_MCP_TITLE = /^mcp\.([^.]+)\.(.+)$/;

const CODEX_TOOL_TITLE = /^Tool: ([^/\s]+)\/(\S+)$/;

const DISPLAY_ENV = ['DISPLAY', 'WAYLAND_DISPLAY', 'XAUTHORITY', 'XDG_RUNTIME_DIR'] as const;

const AGENT_BROWSER_DIR = 'agent-browser';

const NPM_CACHE_KEY = 'npm_config_cache';
const NPM_PREFER_OFFLINE_KEY = 'npm_config_prefer_offline';

export function agentGetsBrowser(agentRef: {
  readonly source: 'registry' | 'custom';
  readonly id: string;
}): boolean {
  return agentRef.source === 'registry' && BROWSER_AGENT_IDS.has(agentRef.id);
}

export type BrowserCallIdentity =
  | { readonly kind: 'none' }
  | { readonly kind: 'browser'; readonly tool: string }
  | { readonly kind: 'unverified' };

export const NOT_A_BROWSER_CALL: BrowserCallIdentity = { kind: 'none' };

const UNVERIFIED_BROWSER_CALL: BrowserCallIdentity = { kind: 'unverified' };

export interface BrowserCallEvidence {
  readonly title?: string | null;
  readonly kind?: string | null;
  readonly rawInput?: unknown;
  readonly _meta?: unknown;
}

function browserServerTool(server: string, tool: string): BrowserCallIdentity {
  if (server !== AGENT_BROWSER_SERVER_NAME) return NOT_A_BROWSER_CALL;
  return BROWSER_TOOL_NAME.test(tool) ? { kind: 'browser', tool } : UNVERIFIED_BROWSER_CALL;
}

function codexMcpCall(call: BrowserCallEvidence): BrowserCallIdentity {
  const match = CODEX_MCP_TITLE.exec((call.title ?? '').trim());
  if (match === null) return UNVERIFIED_BROWSER_CALL;
  const [, server = '', tool = ''] = match;
  return codexNamedCall(call, server, tool);
}

function codexNamedCall(
  call: BrowserCallEvidence,
  server: string,
  tool: string,
): BrowserCallIdentity {
  const input = asRecord(call.rawInput);
  const inputServer = stringField(input, 'server');
  const inputTool = stringField(input, 'tool');
  if (
    (inputServer !== null && inputServer !== server) ||
    (inputTool !== null && inputTool !== tool)
  ) {
    return UNVERIFIED_BROWSER_CALL;
  }
  return browserServerTool(server, tool);
}

export function identifyBrowserCall(
  call: BrowserCallEvidence,
  context: {
    readonly requestMeta?: unknown;
    readonly browserInjected: boolean;
    readonly agentId: string;
  },
): BrowserCallIdentity {
  if (!context.browserInjected) return NOT_A_BROWSER_CALL;
  const meta = asRecord(call._meta);
  const claudeTool = stringField(asRecord(meta?.claudeCode), 'toolName');
  if (claudeTool !== null) {
    const match = CLAUDE_MCP_TOOL.exec(claudeTool);
    return match === null ? NOT_A_BROWSER_CALL : browserServerTool(match[1] ?? '', match[2] ?? '');
  }
  const codex = context.agentId === CODEX_AGENT_ID;
  if (codex && meta?.is_mcp_tool_call === true) return codexMcpCall(call);
  const title = (call.title ?? '').trim();
  const codexTool = codex ? CODEX_TOOL_TITLE.exec(title) : null;
  if (codexTool != null) return codexNamedCall(call, codexTool[1] ?? '', codexTool[2] ?? '');
  const titleTool = BROWSER_TOOL_TITLE.exec(title.toLowerCase())?.[1];
  if (titleTool !== undefined) return { kind: 'browser', tool: titleTool };
  if (!codex) return UNVERIFIED_BROWSER_CALL;
  const input = asRecord(call.rawInput);
  const namedServer =
    stringField(input, 'serverName') ??
    stringField(input, 'server_name') ??
    stringField(input, 'server');
  if (asRecord(context.requestMeta)?.is_mcp_tool_approval === true || namedServer !== null) {
    return namedServer !== null && namedServer.toLowerCase() !== AGENT_BROWSER_SERVER_NAME
      ? NOT_A_BROWSER_CALL
      : UNVERIFIED_BROWSER_CALL;
  }
  const commandOrPatch =
    input !== null && (input.command !== undefined || input.changes !== undefined);
  return call.kind != null && call.kind !== 'other' && commandOrPatch
    ? NOT_A_BROWSER_CALL
    : UNVERIFIED_BROWSER_CALL;
}

export function needsReportedToolCall(
  call: BrowserCallEvidence,
  requestMeta: unknown,
  agentId: string,
): boolean {
  return (
    identifyBrowserCall(call, { requestMeta, browserInjected: true, agentId }).kind === 'unverified'
  );
}

export interface ResolvedBrowserNpx {
  readonly npx: string;
  readonly path: string;
}

export function resolveBrowserNpx(
  pathCandidates: readonly (string | null | undefined)[],
  resolveCommand: (name: string, path: string) => string | null = resolveOnPath,
  accept: (npx: string) => boolean = () => true,
): ResolvedBrowserNpx | null {
  for (const path of pathCandidates) {
    if (path === null || path === undefined || path === '') continue;
    const npx = resolveCommand('npx', path);
    if (npx !== null && accept(npx)) return { npx, path };
  }
  return null;
}

export function npmCacheOf(env: Readonly<Record<string, string>>): string | null {
  for (const [key, value] of Object.entries(env)) {
    if (key.toLowerCase() === NPM_CACHE_KEY && value !== '') return value;
  }
  return null;
}

export type BrowserPackageData = 'cached' | 'fresh';

export function agentBrowserInstallLaunch(
  npx: ResolvedBrowserNpx,
  npmCache: string | null,
  packageData: BrowserPackageData,
  baseEnv: Readonly<Record<string, string>> = mergedEnv(),
): ResolvedLaunch & { kind: 'npx' } {
  const env: Record<string, string> = {};
  for (const [key, value] of Object.entries(baseEnv)) {
    const lower = key.toLowerCase();
    if (lower === 'path' || lower === NPM_PREFER_OFFLINE_KEY) continue;
    if (npmCache !== null && lower === NPM_CACHE_KEY) continue;
    env[key] = value;
  }
  env.PATH = npx.path;
  env[NPM_PREFER_OFFLINE_KEY] = packageData === 'cached' ? 'true' : 'false';
  if (npmCache !== null) env[NPM_CACHE_KEY] = npmCache;
  return { cmd: npx.npx, args: [], env, kind: 'npx', pathFromOverlay: true };
}

function isFile(path: string): boolean {
  try {
    return statSync(path).isFile();
  } catch {
    return false;
  }
}

const AGENT_BROWSER_TOOLS: readonly string[] = [
  'browser_click',
  'browser_close',
  'browser_console_messages',
  'browser_drag',
  'browser_drop',
  'browser_emulate_media',
  'browser_evaluate',
  'browser_file_upload',
  'browser_fill_form',
  'browser_find',
  'browser_handle_dialog',
  'browser_hover',
  'browser_navigate',
  'browser_navigate_back',
  'browser_network_request',
  'browser_network_requests',
  'browser_press_key',
  'browser_resize',
  'browser_select_option',
  'browser_snapshot',
  'browser_tabs',
  'browser_take_screenshot',
  'browser_type',
  'browser_wait_for',
];

const BROWSER_SERVER_RELAY = `(${runBrowserRelay.toString()})(require('node:child_process'), require('node:url'), ${JSON.stringify(AGENT_BROWSER_TOOLS)});`;

export interface AgentBrowserFolders {
  readonly npm: string;
  readonly files: string;
}

export function agentBrowserMcpServer(opts: {
  npx: ResolvedBrowserNpx;
  folders: AgentBrowserFolders;
  npmCache?: string | null;
  platform?: NodeJS.Platform;
  env?: NodeJS.ProcessEnv;
  exists?: (path: string) => boolean;
}): McpServerStdio | null {
  const platform = opts.platform ?? process.platform;
  const env = opts.env ?? process.env;
  const runtime = npxRuntime(opts.npx.npx, platform, opts.exists ?? isFile);
  if (runtime === null) return null;
  const noDisplay =
    platform === 'linux' && (env.DISPLAY ?? '') === '' && (env.WAYLAND_DISPLAY ?? '') === '';
  const displayEnv =
    platform === 'linux' && !noDisplay
      ? DISPLAY_ENV.flatMap((name) => {
          const value = env[name];
          return value === undefined || value === '' ? [] : [{ name, value }];
        })
      : [];
  return {
    name: AGENT_BROWSER_SERVER_NAME,
    command: runtime.node,
    args: [
      '-e',
      BROWSER_SERVER_RELAY,
      opts.folders.npm,
      opts.folders.files,
      ...runtime.npx,
      '--prefix',
      opts.folders.npm,
      '--yes=false',
      AGENT_BROWSER_MCP_PACKAGE,
      '--isolated',
      '--no-webmcp',
      '--output-dir',
      opts.folders.files,
      '--file-paths',
      'absolute',
      ...(noDisplay ? ['--headless'] : []),
    ],
    env: [
      { name: 'PATH', value: opts.npx.path },
      { name: NPM_PREFER_OFFLINE_KEY, value: 'true' },
      ...(opts.npmCache == null ? [] : [{ name: NPM_CACHE_KEY, value: opts.npmCache }]),
      ...displayEnv,
    ],
  };
}

function npxRuntime(
  npx: string,
  platform: NodeJS.Platform,
  exists: (path: string) => boolean,
): { node: string; npx: readonly string[] } | null {
  const nodeDir = dirname(npx);
  if (platform !== 'win32') {
    const node = join(nodeDir, 'node');
    return exists(node) ? { node, npx: [npx] } : null;
  }
  const node = join(nodeDir, 'node.exe');
  const npxCli = join(nodeDir, 'node_modules', 'npm', 'bin', 'npx-cli.js');
  return exists(node) && exists(npxCli) ? { node, npx: [node, npxCli] } : null;
}

export function browserNpxRunnable(
  npx: string,
  opts: { platform?: NodeJS.Platform; exists?: (path: string) => boolean } = {},
): boolean {
  return npxRuntime(npx, opts.platform ?? process.platform, opts.exists ?? isFile) !== null;
}

function agentBrowserPath(root: string, threadId: string): string | null {
  return isMintedThreadId(threadId) ? resolve(root, AGENT_BROWSER_DIR, threadId) : null;
}

export async function prepareAgentBrowserFolders(
  root: string,
  threadId: string,
): Promise<AgentBrowserFolders> {
  const chat = agentBrowserPath(root, threadId);
  if (chat === null) throw new Error('browser folders need a chat id OpenKnowledge minted');
  const folders = { npm: join(chat, 'npm'), files: join(chat, 'files') };
  await tracedMkdir(dirname(chat), { recursive: true, mode: 0o700 });
  await tracedMkdir(chat, { recursive: true, mode: 0o700 });
  await tracedRm(folders.npm, { recursive: true, force: true });
  await tracedMkdir(folders.npm, { mode: 0o700 });
  await tracedWriteFile(
    join(folders.npm, 'package.json'),
    `${JSON.stringify({ name: 'openknowledge-agent-browser', version: '0.0.0', private: true }, null, 2)}\n`,
  );
  await tracedMkdir(folders.files, { recursive: true, mode: 0o700 });
  return folders;
}

export async function removeAgentBrowserFolders(root: string, threadId: string): Promise<void> {
  const chat = agentBrowserPath(root, threadId);
  if (chat === null) return;
  await tracedRm(chat, { recursive: true, force: true });
}