From bc0ddde766b5d01a89945fddda67a4d20d91e266 Mon Sep 17 00:00:00 2001
From: Yida Weng <84164537+YidaWeng@users.noreply.github.com>
Date: Mon, 12 Oct 2026 15:07:29 +0000
Subject: [PATCH 1/2] fix(tui): open local file links with the OS handler
Transcript clicks always went through the HTTP-only browser opener, so
absolute paths and file:// links showed an error toast. Route those
targets through openHref while keeping openUrl strict for auth and docs.
---
packages/tui/src/app.tsx | 4 ++--
packages/tui/src/ui/link.tsx | 6 +++---
packages/util/src/open.test.ts | 24 +++++++++++++++++++++++-
packages/util/src/open.ts | 30 ++++++++++++++++++++++++++++--
4 files changed, 56 insertions(+), 8 deletions(-)
diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index 577cfa11b095..0713b31e8e9a 100644
--- a/packages/tui/src/app.tsx
+++ b/packages/tui/src/app.tsx
@@ -84,7 +84,7 @@ import { Toast, ToastProvider, useToast } from "./ui/toast"
import { isFallbackTitle } from "@opencode/util/session-title-fallback"
import * as Model from "./util/model"
import { ArgsProvider, useArgs, type Args } from "./context/args"
-import { openUrl } from "@opencode/util/open"
+import { openHref, openUrl } from "@opencode/util/open"
import { PromptRefProvider, usePromptRef } from "./context/prompt"
import { Config, ConfigProvider, useConfig } from "./config"
import { newSessionLocation } from "./config/new-session-location"
@@ -1334,7 +1334,7 @@ function App() {
}}
onMouseUp={(event) => {
const url = clickedLink(renderer, event)
- if (url) return void openUrl(url).catch(toast.error)
+ if (url) return void openHref(url).catch(toast.error)
if (copyOnSelectEnabled()) Selection.copyOnSelectRelease(event, renderer, toast, clipboard)
}}
>
diff --git a/packages/tui/src/ui/link.tsx b/packages/tui/src/ui/link.tsx
index caf93e3fff72..1d603d738a02 100644
--- a/packages/tui/src/ui/link.tsx
+++ b/packages/tui/src/ui/link.tsx
@@ -1,6 +1,6 @@
import type { JSX } from "solid-js"
import type { CliRenderer, MouseEvent, RGBA } from "@opentui/core"
-import { openUrl } from "@opencode/util/open"
+import { openHref } from "@opencode/util/open"
export interface LinkProps {
href: string
@@ -13,7 +13,7 @@ export interface LinkProps {
/**
* Link component that renders clickable hyperlinks.
- * Clicking anywhere on the link text opens the URL in the default browser.
+ * Clicking anywhere on the link text opens http(s) URLs in the browser, or local file paths with the OS handler.
*/
export function Link(props: LinkProps) {
const displayText = props.children ?? props.href
@@ -25,7 +25,7 @@ export function Link(props: LinkProps) {
width={props.width}
wrapMode={props.wrapMode}
onMouseUp={() => {
- openUrl(props.href).catch(() => {})
+ openHref(props.href).catch(() => {})
}}
>
{displayText}
diff --git a/packages/util/src/open.test.ts b/packages/util/src/open.test.ts
index 36c65391ab8e..2bbf048d0233 100644
--- a/packages/util/src/open.test.ts
+++ b/packages/util/src/open.test.ts
@@ -1,5 +1,7 @@
import { describe, expect, test } from "bun:test"
-import { openUrl } from "./open.js"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+import { openUrl, resolveOpenTarget } from "./open.js"
describe("openUrl", () => {
test("rejects values that are not URLs", async () => {
@@ -14,3 +16,23 @@ describe("openUrl", () => {
await expect(openUrl("\\\\server\\share\\file.html")).rejects.toThrow("Only http and https links")
})
})
+
+describe("resolveOpenTarget", () => {
+ test("keeps http and https URLs for the browser", () => {
+ expect(resolveOpenTarget("https://example.com/docs")).toBe("https://example.com/docs")
+ expect(resolveOpenTarget("http://127.0.0.1:4096")).toBe("http://127.0.0.1:4096/")
+ })
+
+ test("maps local file URLs and absolute paths to filesystem paths", () => {
+ const file = path.join(path.resolve("/tmp"), "example.md")
+ expect(resolveOpenTarget(pathToFileURL(file).href)).toBe(file)
+ expect(resolveOpenTarget(file)).toBe(file)
+ })
+
+ test("rejects remote file URLs and unsafe schemes", () => {
+ expect(resolveOpenTarget("file://example.com/share/index.html")).toBeUndefined()
+ expect(resolveOpenTarget("javascript:alert(1)")).toBeUndefined()
+ expect(resolveOpenTarget("packages/tui/src/ui/link.tsx")).toBeUndefined()
+ expect(resolveOpenTarget("not a url")).toBeUndefined()
+ })
+})
diff --git a/packages/util/src/open.ts b/packages/util/src/open.ts
index 2ed0760dd41c..4c95c23741ec 100644
--- a/packages/util/src/open.ts
+++ b/packages/util/src/open.ts
@@ -1,4 +1,6 @@
import open from "open"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
export function openUrl(input: string) {
const url = URL.canParse(input) ? new URL(input) : undefined
@@ -7,6 +9,30 @@ export function openUrl(input: string) {
return open(url.href)
}
-export function openPath(path: string) {
- return open(path)
+export function openPath(target: string) {
+ return open(target)
+}
+
+/** Open an http(s) URL in the browser, or a local file path / file:// link with the OS handler. */
+export function openHref(input: string) {
+ const target = resolveOpenTarget(input)
+ if (!target) return Promise.reject(new Error(`Only http, https, and local file links can be opened: ${input}`))
+ return open(target)
+}
+
+/** @internal */
+export function resolveOpenTarget(input: string) {
+ if (URL.canParse(input)) {
+ const url = new URL(input)
+ if (url.protocol === "http:" || url.protocol === "https:") return url.href
+ // Match desktop: only local file URLs (no host) become filesystem paths.
+ if (url.protocol === "file:" && !url.hostname) {
+ try {
+ return fileURLToPath(url.href)
+ } catch {
+ return undefined
+ }
+ }
+ }
+ if (path.isAbsolute(input)) return input
}
From db5fbf46478ed4590045dc7c6b79dd7c7af92283 Mon Sep 17 00:00:00 2001
From: Yida Weng <84164537+YidaWeng@users.noreply.github.com>
Date: Mon, 12 Oct 2026 15:37:02 +0000
Subject: [PATCH 2/2] fix(tui): resolve relative file links against the session
directory
Address review feedback on #54838: resolve project-relative Markdown
paths before opening, skip any modified click so the terminal can handle
Cmd-click, and avoid toasting when a link cannot be opened.
---
packages/tui/src/app.tsx | 11 +++++++++--
packages/tui/src/ui/link.tsx | 5 +++--
packages/tui/test/ui/link.test.tsx | 2 ++
packages/util/src/open.test.ts | 10 +++++++++-
packages/util/src/open.ts | 9 ++++++---
5 files changed, 29 insertions(+), 8 deletions(-)
diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index 0713b31e8e9a..038ef9dfe59d 100644
--- a/packages/tui/src/app.tsx
+++ b/packages/tui/src/app.tsx
@@ -37,6 +37,7 @@ import {
TuiStartupProvider,
TuiTerminalEnvironmentProvider,
useTuiApp,
+ useTuiPaths,
useTuiStartup,
useTuiTerminalEnvironment,
type TuiApp,
@@ -84,7 +85,7 @@ import { Toast, ToastProvider, useToast } from "./ui/toast"
import { isFallbackTitle } from "@opencode/util/session-title-fallback"
import * as Model from "./util/model"
import { ArgsProvider, useArgs, type Args } from "./context/args"
-import { openHref, openUrl } from "@opencode/util/open"
+import { openHref, openUrl, resolveOpenTarget } from "@opencode/util/open"
import { PromptRefProvider, usePromptRef } from "./context/prompt"
import { Config, ConfigProvider, useConfig } from "./config"
import { newSessionLocation } from "./config/new-session-location"
@@ -453,6 +454,7 @@ export const run = Effect.fn("Tui.run")(function* (input: TuiInput) {
function App() {
const app = useTuiApp()
+ const paths = useTuiPaths()
const startup = useTuiStartup()
const config = useConfig()
const devtools = createMemo(() => config.data.debug?.devtools ?? app.channel === "local")
@@ -477,6 +479,7 @@ function App() {
const plugins = usePlugin()
const clipboard = useClipboard()
const terminalEnvironment = useTuiTerminalEnvironment()
+ const linkBase = () => location.current?.directory || paths.cwd
let paletteTimer: ReturnType | undefined
const afterFrame = () => {
// The native writer can still be flushing the frame when FRAME fires. Keep OSC probes behind visible app output.
@@ -1334,7 +1337,11 @@ function App() {
}}
onMouseUp={(event) => {
const url = clickedLink(renderer, event)
- if (url) return void openHref(url).catch(toast.error)
+ if (url) {
+ const base = linkBase()
+ // Skip links we cannot open so the terminal/IDE can handle them (e.g. Cmd-click).
+ if (resolveOpenTarget(url, base)) return void openHref(url, base).catch(toast.error)
+ }
if (copyOnSelectEnabled()) Selection.copyOnSelectRelease(event, renderer, toast, clipboard)
}}
>
diff --git a/packages/tui/src/ui/link.tsx b/packages/tui/src/ui/link.tsx
index 1d603d738a02..9a980f282d3f 100644
--- a/packages/tui/src/ui/link.tsx
+++ b/packages/tui/src/ui/link.tsx
@@ -37,10 +37,11 @@ export function Link(props: LinkProps) {
* Returns the hyperlink under a plain left click. opentui marks the release that ends a selection gesture with
* `isDragging`, and a fresh "cell" selection means the pointer never moved; other releases, such as the end of a drag
* that started outside text, are not clicks. Each rendered cell stores its full URL, so a click on any row of a wrapped
- * link resolves the whole link. Modified clicks are left to the terminal's own hyperlink handling.
+ * link resolves the whole link. Modified clicks (including Cmd/meta when the terminal reports it) are left to the
+ * terminal's own hyperlink handling.
*/
export function clickedLink(renderer: CliRenderer, event: MouseEvent) {
- if (!event.isDragging || event.modifiers.ctrl || event.modifiers.alt || event.modifiers.shift) return
+ if (!event.isDragging || Object.values(event.modifiers).some(Boolean)) return
const selection = renderer.getSelection()
if (!selection?.isStart || selection.behavior !== "cell") return
return renderer.getLinkAt(event.x, event.y) ?? undefined
diff --git a/packages/tui/test/ui/link.test.tsx b/packages/tui/test/ui/link.test.tsx
index 0aded5faeb61..d1f3a7308301 100644
--- a/packages/tui/test/ui/link.test.tsx
+++ b/packages/tui/test/ui/link.test.tsx
@@ -44,6 +44,8 @@ test("plain clicks on any row of a wrapped Markdown link resolve the full URL",
await app.mockMouse.click(0, head)
await app.mockMouse.click(x, head, 0, { modifiers: { ctrl: true } })
await app.mockMouse.click(x, head, 0, { modifiers: { shift: true } })
+ await app.mockMouse.click(x, head, 0, { modifiers: { alt: true } })
+ await app.mockMouse.click(x, head, 0, { modifiers: { meta: true } as never })
await app.mockMouse.click(x, head, 2)
await app.mockMouse.drag(0, head, x + 2, head)
await app.mockMouse.drag(0, 0, x + 2, head)
diff --git a/packages/util/src/open.test.ts b/packages/util/src/open.test.ts
index 2bbf048d0233..eca081707fba 100644
--- a/packages/util/src/open.test.ts
+++ b/packages/util/src/open.test.ts
@@ -29,9 +29,17 @@ describe("resolveOpenTarget", () => {
expect(resolveOpenTarget(file)).toBe(file)
})
- test("rejects remote file URLs and unsafe schemes", () => {
+ test("resolves relative paths against a session directory base", () => {
+ const base = path.resolve("/repo")
+ expect(resolveOpenTarget("plan/example.md", base)).toBe(path.join(base, "plan/example.md"))
+ expect(resolveOpenTarget("./src/foo.ts", base)).toBe(path.join(base, "src/foo.ts"))
+ expect(resolveOpenTarget("../sibling.md", base)).toBe(path.resolve(base, "../sibling.md"))
+ })
+
+ test("rejects remote file URLs, anchors, and unsafe schemes", () => {
expect(resolveOpenTarget("file://example.com/share/index.html")).toBeUndefined()
expect(resolveOpenTarget("javascript:alert(1)")).toBeUndefined()
+ expect(resolveOpenTarget("#section", "/repo")).toBeUndefined()
expect(resolveOpenTarget("packages/tui/src/ui/link.tsx")).toBeUndefined()
expect(resolveOpenTarget("not a url")).toBeUndefined()
})
diff --git a/packages/util/src/open.ts b/packages/util/src/open.ts
index 4c95c23741ec..982ee0edf15b 100644
--- a/packages/util/src/open.ts
+++ b/packages/util/src/open.ts
@@ -14,14 +14,14 @@ export function openPath(target: string) {
}
/** Open an http(s) URL in the browser, or a local file path / file:// link with the OS handler. */
-export function openHref(input: string) {
- const target = resolveOpenTarget(input)
+export function openHref(input: string, base?: string) {
+ const target = resolveOpenTarget(input, base)
if (!target) return Promise.reject(new Error(`Only http, https, and local file links can be opened: ${input}`))
return open(target)
}
/** @internal */
-export function resolveOpenTarget(input: string) {
+export function resolveOpenTarget(input: string, base?: string) {
if (URL.canParse(input)) {
const url = new URL(input)
if (url.protocol === "http:" || url.protocol === "https:") return url.href
@@ -33,6 +33,9 @@ export function resolveOpenTarget(input: string) {
return undefined
}
}
+ return undefined
}
if (path.isAbsolute(input)) return input
+ // Resolve project-relative Markdown links such as plan/example.md against the session directory.
+ if (base !== undefined && input.length > 0 && !input.startsWith("#")) return path.resolve(base, input)
}