fix(terminal): open links externally

Author: johannesjo

electron/ipc/channels.ts

@@ -84,6 +84,7 @@ export enum IPC {
   ShellReveal = '__shell_reveal',
   ShellOpenFile = '__shell_open_file',
   ShellOpenInEditor = '__shell_open_in_editor',
+  ShellOpenExternal = '__shell_open_external',
 
   // Arena
   SaveArenaData = 'save_arena_data',

electron/ipc/register.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { selectMcpJsonDir } from './register.js';
+import { openExternalHttpUrl, selectMcpJsonDir, validateExternalHttpUrl } from './register.js';
 
 describe('selectMcpJsonDir', () => {
   it('returns worktreePath when defined', () => {
@@ -14,3 +14,62 @@ describe('selectMcpJsonDir', () => {
     expect(selectMcpJsonDir('', '/project')).toBe('');
   });
 });
+
+describe('validateExternalHttpUrl', () => {
+  it('accepts http and https URLs', () => {
+    expect(validateExternalHttpUrl('https://example.com/path?q=1')).toBe(
+      'https://example.com/path?q=1',
+    );
+    expect(validateExternalHttpUrl('http://example.com/')).toBe('http://example.com/');
+  });
+
+  it('normalizes protocol and host casing', () => {
+    expect(validateExternalHttpUrl('HTTPS://EXAMPLE.COM/pr/1')).toBe('https://example.com/pr/1');
+  });
+
+  it('rejects non-web protocols', () => {
+    expect(() => validateExternalHttpUrl('file:///etc/passwd')).toThrow(
+      'url must use http or https',
+    );
+    expect(() => validateExternalHttpUrl('javascript:alert(1)')).toThrow(
+      'url must use http or https',
+    );
+  });
+
+  it('rejects invalid and non-string values', () => {
+    expect(() => validateExternalHttpUrl('not a url')).toThrow('url must be a valid URL');
+    expect(() => validateExternalHttpUrl(undefined)).toThrow('url must be a string');
+  });
+});
+
+describe('openExternalHttpUrl', () => {
+  it('opens the normalized URL', async () => {
+    const opened: string[] = [];
+
+    await openExternalHttpUrl('HTTPS://EXAMPLE.COM/pr/1', async (url) => {
+      opened.push(url);
+    });
+
+    expect(opened).toEqual(['https://example.com/pr/1']);
+  });
+
+  it('does not call the opener for invalid URLs', async () => {
+    const opened: string[] = [];
+
+    await expect(
+      openExternalHttpUrl('file:///etc/passwd', async (url) => {
+        opened.push(url);
+      }),
+    ).rejects.toThrow('url must use http or https');
+
+    expect(opened).toEqual([]);
+  });
+
+  it('does not include the URL in opener failure errors', async () => {
+    await expect(
+      openExternalHttpUrl('https://example.com/?token=secret', async (url) => {
+        throw new Error(`OS refused ${url}`);
+      }),
+    ).rejects.toThrow('Failed to open external URL');
+  });
+});

electron/ipc/register.ts

@@ -219,6 +219,32 @@ function validateRelativePath(p: unknown, label: string): void {
   if (p.includes('..')) throw new Error(`${label} must not contain ".."`);
 }
 
+export function validateExternalHttpUrl(rawUrl: unknown): string {
+  assertString(rawUrl, 'url');
+  let parsed: URL;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error('url must be a valid URL');
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error('url must use http or https');
+  }
+  return parsed.href;
+}
+
+export async function openExternalHttpUrl(
+  rawUrl: unknown,
+  openExternal: (url: string) => Promise<void> = shell.openExternal,
+): Promise<void> {
+  const url = validateExternalHttpUrl(rawUrl);
+  try {
+    await openExternal(url);
+  } catch {
+    throw new Error('Failed to open external URL');
+  }
+}
+
 const validateBranchName = sharedValidateBranchName;
 
 /** Reject commit hashes that are not valid hex strings. */
@@ -1119,6 +1145,10 @@ export function registerAllHandlers(win: BrowserWindow): void {
     return shell.openPath(path.join(args.worktreePath, args.filePath));
   });
 
+  ipcMain.handle(IPC.ShellOpenExternal, async (_e, args) => {
+    await openExternalHttpUrl(args.url);
+  });
+
   ipcMain.handle(IPC.ShellOpenInEditor, (_e, args) => {
     validatePath(args.worktreePath, 'worktreePath');
     if (typeof args.editorCommand !== 'string' || !args.editorCommand.trim()) {

electron/ipc/trace.ts

@@ -34,6 +34,7 @@ const NEVER_SAFE: ReadonlySet<string> = new Set<string>([
   IPC.ShellOpenInEditor,
   IPC.ShellOpenFile,
   IPC.ShellReveal,
+  IPC.ShellOpenExternal,
   IPC.DialogOpen,
   IPC.OpenPath,
   IPC.ReadFileText,

electron/preload.cjs

@@ -82,6 +82,7 @@ const ALLOWED_CHANNELS = new Set([
   '__shell_reveal',
   '__shell_open_file',
   '__shell_open_in_editor',
+  '__shell_open_external',
   // Arena
   'save_arena_data',
   'load_arena_data',

src/components/TerminalView.tsx

@@ -31,6 +31,7 @@ import {
 import { dataTransferToShellArgs, escapePath } from '../lib/terminalDrop';
 import { cleanCopiedTerminalText } from '../lib/copy-text';
 import { hasTerminalUserActivity, nextTerminalInputPending } from '../lib/terminalInputPending';
+import { createTerminalHttpLinkHandler } from '../lib/terminalLinks';
 import type { PtyOutput } from '../ipc/types';
 
 let windowUnloading = false;
@@ -90,6 +91,13 @@ interface TerminalViewProps {
 // expensive full-chunk decoding during large terminal bursts.
 const STATUS_ANALYSIS_MAX_BYTES = 8 * 1024;
 
+const openTerminalHttpLinkWithModifier = createTerminalHttpLinkHandler({
+  isMac,
+  requireModifier: true,
+  openExternal: (url) => invoke(IPC.ShellOpenExternal, { url }),
+  onOpenError: () => logWarn('terminal.link', 'Failed to open external URL'),
+});
+
 /** Terminal-layer bindings — filtered from resolved bindings.
  *  Called in the key handler (hot path); resolveBindings walks the full
  *  defaults list on each call, which is fine at human typing speed. */
@@ -137,24 +145,15 @@ export function TerminalView(props: TerminalViewProps) {
       allowProposedApi: true,
       scrollback: TERMINAL_SCROLLBACK_LINES,
       disableStdin: taskPtyDetached(),
+      linkHandler: {
+        activate: openTerminalHttpLinkWithModifier,
+        allowNonHttpProtocols: false,
+      },
     });
 
     fitAddon = new FitAddon();
     term.loadAddon(fitAddon);
-    term.loadAddon(
-      new WebLinksAddon((event, uri) => {
-        // Require Cmd+click (Mac) or Ctrl+click (Linux) to open links
-        if (!(isMac ? event.metaKey : event.ctrlKey)) return;
-        try {
-          const parsed = new URL(uri);
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
-            window.open(uri, '_blank');
-          }
-        } catch {
-          // Invalid URL, ignore
-        }
-      }),
-    );
+    term.loadAddon(new WebLinksAddon(openTerminalHttpLinkWithModifier));
 
     term.open(containerRef);
 

src/lib/terminalLinks.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createTerminalHttpLinkHandler, normalizeHttpUrl } from './terminalLinks';
+
+function event(overrides: Partial<MouseEvent> = {}) {
+  return {
+    ctrlKey: false,
+    metaKey: false,
+    preventDefault: vi.fn(),
+    stopPropagation: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe('normalizeHttpUrl', () => {
+  it('accepts and normalizes web URLs', () => {
+    expect(normalizeHttpUrl('HTTPS://EXAMPLE.COM/pr/1')).toBe('https://example.com/pr/1');
+  });
+
+  it('rejects invalid and non-web URLs', () => {
+    expect(normalizeHttpUrl('file:///etc/passwd')).toBeNull();
+    expect(normalizeHttpUrl('javascript:alert(1)')).toBeNull();
+    expect(normalizeHttpUrl('not a url')).toBeNull();
+  });
+});
+
+describe('createTerminalHttpLinkHandler', () => {
+  it('does nothing for unmodified desktop clicks when a modifier is required', () => {
+    const openExternal = vi.fn();
+    const e = event();
+    const handler = createTerminalHttpLinkHandler({
+      isMac: false,
+      requireModifier: true,
+      openExternal,
+    });
+
+    handler(e, 'https://example.com/');
+
+    expect(openExternal).not.toHaveBeenCalled();
+    expect(e.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it('opens with Ctrl on non-mac platforms', () => {
+    const openExternal = vi.fn();
+    const e = event({ ctrlKey: true });
+    const handler = createTerminalHttpLinkHandler({
+      isMac: false,
+      requireModifier: true,
+      openExternal,
+    });
+
+    handler(e, 'HTTPS://EXAMPLE.COM/pr/1');
+
+    expect(openExternal).toHaveBeenCalledWith('https://example.com/pr/1');
+    expect(e.preventDefault).toHaveBeenCalledTimes(1);
+    expect(e.stopPropagation).not.toHaveBeenCalled();
+  });
+
+  it('opens with Cmd on macOS', () => {
+    const openExternal = vi.fn();
+    const e = event({ metaKey: true });
+    const handler = createTerminalHttpLinkHandler({
+      isMac: true,
+      requireModifier: true,
+      openExternal,
+    });
+
+    handler(e, 'https://example.com/');
+
+    expect(openExternal).toHaveBeenCalledWith('https://example.com/');
+  });
+
+  it('blocks invalid URLs after taking over the click', () => {
+    const openExternal = vi.fn();
+    const e = event({ ctrlKey: true });
+    const handler = createTerminalHttpLinkHandler({
+      isMac: false,
+      requireModifier: true,
+      openExternal,
+    });
+
+    handler(e, 'javascript:alert(1)');
+
+    expect(openExternal).not.toHaveBeenCalled();
+    expect(e.preventDefault).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports opener failures without throwing', async () => {
+    const onOpenError = vi.fn();
+    const handler = createTerminalHttpLinkHandler({
+      isMac: false,
+      openExternal: () => Promise.reject(new Error('failed')),
+      onOpenError,
+    });
+
+    handler(event(), 'https://example.com/');
+    await Promise.resolve();
+
+    expect(onOpenError).toHaveBeenCalledTimes(1);
+  });
+});

src/lib/terminalLinks.ts

@@ -0,0 +1,38 @@
+export interface TerminalLinkMouseEvent {
+  ctrlKey: boolean;
+  metaKey: boolean;
+  preventDefault: () => void;
+}
+
+export interface TerminalLinkHandlerOptions {
+  isMac: boolean;
+  openExternal: (url: string) => Promise<void> | void;
+  onOpenError?: () => void;
+  requireModifier?: boolean;
+}
+
+export function normalizeHttpUrl(uri: string): string | null {
+  try {
+    const parsed = new URL(uri);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+    return parsed.href;
+  } catch {
+    return null;
+  }
+}
+
+export function createTerminalHttpLinkHandler(options: TerminalLinkHandlerOptions) {
+  return (event: TerminalLinkMouseEvent, uri: string): void => {
+    if (options.requireModifier && !(options.isMac ? event.metaKey : event.ctrlKey)) return;
+
+    event.preventDefault();
+    const url = normalizeHttpUrl(uri);
+    if (!url) return;
+
+    try {
+      Promise.resolve(options.openExternal(url)).catch(() => options.onOpenError?.());
+    } catch {
+      options.onOpenError?.();
+    }
+  };
+}

src/remote/AgentDetail.tsx

@@ -2,6 +2,7 @@ import { onMount, onCleanup, createSignal, Show } from 'solid-js';
 import { Terminal } from '@xterm/xterm';
 import { FitAddon } from '@xterm/addon-fit';
 import { TERMINAL_SCROLLBACK_LINES, base64ToUint8Array } from '../lib/terminalConstants';
+import { createTerminalHttpLinkHandler } from '../lib/terminalLinks';
 import { subscribeAgent, unsubscribeAgent, onOutput, onScrollback, agents, status } from './ws';
 
 interface AgentDetailProps {
@@ -10,6 +11,13 @@ interface AgentDetailProps {
   onBack: () => void;
 }
 
+const openRemoteHttpLink = createTerminalHttpLinkHandler({
+  isMac: false,
+  openExternal: (url) => {
+    window.open(url, '_blank', 'noopener,noreferrer');
+  },
+});
+
 export function AgentDetail(props: AgentDetailProps) {
   let termContainer: HTMLDivElement | undefined;
   let term: Terminal | undefined;
@@ -41,6 +49,10 @@ export function AgentDetail(props: AgentDetailProps) {
       cursorBlink: false,
       disableStdin: true,
       convertEol: false,
+      linkHandler: {
+        activate: openRemoteHttpLink,
+        allowNonHttpProtocols: false,
+      },
     });
 
     fitAddon = new FitAddon();