/docs/plans/experimental-chat-file-links.md

Experimental Chat File Links

Problem

Codex is emitting local file references as absolute-path markdown links because the upstream prompt bundle says:

• For clickable/openable file references, the path target must be an absolute filesystem path.
• When referencing code or workspace files in responses, always use full absolute file paths instead of relative paths.

Happy does not currently implement that contract. The chat renderer only handles:

• explicit markdown links
• bare http(s) URLs

That creates two broken cases:

1. Absolute markdown file links are treated as ordinary browser links on web, so /Users/.../file.ts:12 becomes http://localhost/....
2. Bare relative file refs like packages/foo.ts:12 are rendered as plain text because they are never auto-linkified.

Goals

• Gate the entire feature behind the existing experiments setting.
• Support both absolute and relative file refs in chat.
• Route file refs into the internal file viewer instead of the browser.
• Canonicalize paths before calling the RPC layer.
• Keep external links working exactly as they do today.

Control Flow

1. Parse markdown as today.
2. When rendering spans:
   • If experiments is off, keep existing behavior.
   • If a span is inline code, do not auto-link file refs.
   • If a span already has a URL, try to parse it as a file ref first.
   • If a span is plain text, scan whitespace-delimited tokens for file refs.
3. If a candidate parses as a file ref:
   • Resolve it to one canonical absolute path.
   • Push /session/:id/file?path=<base64(abs)>&line=<n>&column=<n>.
   • Do not expose it as a browser href.
4. In the file viewer:
   • Decode the incoming path.
   • Resolve relative input against the session root.
   • Normalize to a canonical absolute path.
   • Read the file through RPC using the canonical absolute path.
   • If the file is inside the session root, compute a repo-relative path for git diff.
   • If the file is outside the session root, skip diff and show the file directly.
5. In the RPC layer:
   • Resolve the incoming path to a canonical absolute path.
   • Validate access using the canonical absolute path.
   • Read/write/list using the canonical absolute path, not the raw input.

Supported Cases

• Explicit markdown absolute links like [foo.ts:12](/Users/me/repo/foo.ts:12)
• Explicit markdown relative links like [foo.ts:12](packages/app/foo.ts:12)
• Bare absolute refs like /Users/me/repo/foo.ts:12
• Bare relative refs like packages/app/foo.ts:12
• Optional :line
• Optional :line:column
• Windows drive paths like C:\repo\foo.ts:12

Rejected Cases

• External URLs like https://...
• URI schemes like mailto: and node:
• Plain prose tokens that do not look file-like
• Inline code spans and fenced code blocks

Viewer Semantics

• The route accepts either absolute or relative path values for backwards compatibility.
• Internally, the viewer normalizes to a canonical absolute path.
• Diff view is shown only when the file is inside the session root and git diff returns content.
• A line query forces file view and scrolls near the requested line.

RPC Semantics

• validatePath() should return the resolved canonical path.
• Callers should use resolvedPath for filesystem operations.
• This keeps the app and CLI aligned on one path representation.