fix(frontend): encode artifact URL path segments

[VectorPeak]

Fix artifact URL construction so reserved characters in generated artifact filenames stay inside the path instead of being parsed as URL syntax.

What Problem This Solves

urlOfArtifact() and resolveArtifactURL() are the frontend helpers that turn a thread id plus an artifact virtual path into links for artifact previews, markdown images, and downloads. Before this change, those helpers interpolated the raw filepath directly into the URL string:

/api/threads/{thread_id}/artifacts{filepath}

That is fragile because a URL path is not just plain text. Characters such as # and ? have structural meaning: # starts the fragment and ? starts the query string. When those characters appear inside a generated artifact filename, the browser parses them before the request reaches the gateway.

/mnt/user-data/outputs/a#b.txt -> pathname ends at /a, hash is #b.txt
/mnt/user-data/outputs/a?b.txt -> pathname ends at /a, search is ?b.txt

The backend artifact route expects the full virtual path at /api/threads/{thread_id}/artifacts/{path}. If the browser truncates the path first, the gateway receives a request for the wrong artifact. The visible effect is that otherwise valid generated filenames can fail in artifact preview, markdown image rendering, or download links.

Changes

The production change is intentionally small and limited to frontend URL construction:

+function encodeArtifactPath(filepath: string) {
+  return filepath.split("/").map(encodeURIComponent).join("/");
+}

• Encode artifact paths segment-by-segment so /mnt/user-data/... keeps its / path structure while filename segments like a#b?.txt become a%23b%3F.txt.
• Encode threadId in the same artifact URL helpers so the full route is assembled from URL-safe dynamic segments.
• Keep the existing download=true query parameter behavior unchanged; it is still appended after the encoded path.
• Apply the same path encoding to gateway artifact URLs, mock artifact URLs, and static demo artifact URLs.
• Leave backend artifact storage, path resolution, authorization, response headers, MIME handling, and upload deletion behavior unchanged.

Evidence

Before the fix, a browser URL parser treats filename characters as URL separators, so the route path is shortened before the request can reach FastAPI:

raw /api/threads/thread-1/artifacts/mnt/user-data/outputs/a  #b.txt
raw /api/threads/thread-1/artifacts/mnt/user-data/outputs/a ?b.txt

With segment-level encoding, the same filenames remain inside the path and no accidental query or fragment is produced:

enc /api/threads/thread-1/artifacts/mnt/user-data/outputs/a%23b.txt
enc /api/threads/thread-1/artifacts/mnt/user-data/outputs/a%3Fb.txt

The regression tests pin the important cases directly in frontend/tests/unit/core/artifacts/utils.test.ts:

/mnt/user-data/outputs/a#b?.txt -> /mnt/user-data/outputs/a%23b%3F.txt
/mnt/user-data/outputs/中 文#?.png -> /mnt/user-data/outputs/%E4%B8%AD%20%E6%96%87%23%3F.png

They also cover the static demo path so the same reserved-character behavior is consistent outside the live gateway flow.

Possible call chain / impact

Artifact UI / markdown image / download link
  -> urlOfArtifact() or resolveArtifactURL()
  -> frontend constructs /api/threads/{thread_id}/artifacts/{path}
  -> browser parses the URL
  -> gateway artifact router receives the decoded artifact path

This PR changes only the frontend helper layer in that chain. The intended boundary is to make the URL safe before the browser parser sees it, rather than adding special cases to the backend after the path has already been truncated.

Sibling surfaces checked:

• urlOfArtifact() covers artifact detail links, preview sources, file list download links, and the artifact loader.
• resolveArtifactURL() covers absolute artifact paths and message image rewriting through resolveMessageImageURL().
• Mock and static demo artifact URLs now use the same path-segment encoding.
• Upload deletion is intentionally not changed here; it is a separate upload API surface and is already covered by another open PR.

Testing / Validation

Local validation was run on Windows with Node v24.15.0 and pnpm 10.26.2; GitHub Actions will re-run on the repo's pinned Node 22 environment.

• pnpm test tests/unit/core/artifacts/utils.test.ts — 6 passed
• pnpm test — 646 passed
• pnpm format — passed
• pnpm lint — passed
• pnpm typecheck — passed
• BETTER_AUTH_SECRET=local-dev-secret pnpm build — passed; emitted the existing Turbopack NFT-list warning from the mock artifact route

[CLAassistant]

All committers have signed the CLA.

[willem-bd]

The core fix is correct and well-scoped: segment-wise encodeURIComponent is the right approach, the backend route (/api/threads/{thread_id}/artifacts/{path:path} + Starlette auto-decode) is the correct counterpart, and encoding threadId brings these helpers in line with the rest of the codebase (which already encodes it). pnpm checks pass.

The comments below are non-blocking edge-case observations at the markdown-link / resolveMessageImageURL boundary, where the input is model-authored rather than a backend-provided artifact path — exactly the inputs the PR's stated scope ("generated artifact filenames") doesn't fully cover. They're low-probability but real, and currently untested.

[willem-bd]

When this is reached via resolveMessageImageURL's /mnt/ branch (line 51: if (src.startsWith("/mnt/")) return resolveArtifactURL(src, threadId)), absolutePath is the raw markdown image src, which may carry a ?query or #fragment — e.g. ![img](/mnt/.../chart.png?v=2) (cache-buster) or …/report.html#section (fragment nav). encodeArtifactPath now encodes those into the path (chart.png%3Fv%3D2), so the backend looks for a file literally named chart.png?v=2 → 404.

The relative-path branch below deliberately splits ?/# off src and re-appends them as a real query/fragment (${resolveArtifactURL(...)}${src.slice(relativePath.length)}), preserving their meaning. The /mnt/ branch doesn't, so after this PR the two branches disagree on what ?/# mean for the same logical input.

Suggestion: split ?/# in the /mnt/ branch the same way (or document that /mnt/ srcs must not carry query/fragment), and add a test for resolveMessageImageURL("/mnt/.../chart.png?v=2", …).

[VectorPeak]

Addressed in 60bfbd9. The /mnt/ markdown path now splits off ?query/#fragment before resolving the artifact URL, then re-appends that suffix as the real URL query/fragment. I also added coverage for resolveMessageImageURL with a /mnt/ src carrying query and fragment.

[willem-bd]

encodeURIComponent re-encodes %, so this double-encodes already-percent-encoded input: a%23b.txt → a%2523b.txt, which the backend decodes once to a literal a%23b.txt instead of a#b.txt.

This only affects callers passing model-authored paths: markdown-link.tsx (resolveArtifactURL(href, …) on a /mnt/ markdown href) and resolveMessageImageURL (markdown image src). If the model emits a pre-encoded href/src, this regresses vs. the previous pass-through (which left %23 for the browser to decode to #). Backend-provided paths (present_file_tool, workspace-changes, <uploaded_files>) are raw, so they're unaffected.

The write-file: caller in artifact-file-detail.tsx already does decodeURIComponent(url.pathname) before passing the path down — a decode-before-encode precedent. Consider making encodeArtifactPath idempotent (decode first), or confirm markdown hrefs/srcs can never arrive pre-encoded.

[VectorPeak]

Addressed in 60bfbd9. Artifact path segments are now decoded before being encoded again, with a safe fallback for malformed percent-encoding, so pre-encoded markdown inputs such as a%23b%3F.txt remain idempotent instead of becoming double-encoded.

[willem-bd]

The added tests cover the three URL builders for #/?/Unicode — nice. Two gaps worth pinning:

1. resolveMessageImageURL with a /mnt/ src carrying a ?query/#fragment (the case whose behavior changes in this PR — see the comment on resolveArtifactURL). No test pins the intended result, so the asymmetry with the relative-path branch is unguarded.
2. The relative-path branch with a reserved character in the artifact path itself — the existing #detail test only exercises the src suffix.

Locking these in would guard both branches against future drift.

[VectorPeak]

Addressed in 60bfbd9. Added tests for the /mnt/ resolveMessageImageURL query/fragment case, idempotent pre-encoded artifact paths, and a relative markdown image path whose artifact filename contains reserved characters.