fix(opencode): cache policy + etag for the embedded web UI - #51875

The following comment was made by an LLM, it may be inaccurate:

cc @thdxr @adamdotdevin — requesting review when you get a chance.

Fix details:

Embedded UI responses previously sent only content-type (+ CSP for HTML). With no cache directives, browsers apply heuristic caching — a stale index.html after an upgrade pins users to an old bundle, which is one of the mechanisms behind the recurring "stale UI" reports.

The policy split mirrors the build output shape:

• no-cache for index.html, site.webmanifest, icons, oc-theme-preload.js and the verbatim public/assets/ files — these keep the same URL across releases, so they must revalidate every load.
• public, max-age=31536000, immutable only for assets/<name>-<hash>.<ext> — the hash detection is on the file path (normalized for Windows separators), matching Vite's [name]-[hash] emission; unhashed files that happen to live under assets/ (e.g. Inter.ttf) are not matched.
• ETag = sha256(body)[:32] on every embedded response, with If-None-Match → 304 so no-cache revalidations cost a header roundtrip, not the body.
• x-opencode-version exposes the server version on every UI response — a building block for the version-mismatch surface proposed in [FEATURE]: web: connection health surface — stream status, reconnect progress, client/server version mismatch #51860.

The proxied (--disable-embedded-web-ui) path is untouched — it still forwards app.opencode.ai's own headers.

New test covers all three cache classes + the conditional-request path: 13/13 pass in httpapi-ui.test.ts, typecheck clean.

Embedded UI responses send no cache directives, so a stale index.html can pin a browser to the previous bundle after an upgrade.

Head 4a8754c5d6dd5e33dd6352d00d4b4d0c3b1a11f5 is unchanged from the tested tip.

Fork leaf kvnloo#197 recorded fail→pass on packages/opencode/test/server/httpapi-ui.test.ts (13 pass, 1 fail with the assertion removed, 13 pass after restore).

That locks hashed assets as immutable and HTML as no-cache. It does not change the UI itself.

Reviewed — the cache policy split is correct, and crucially the failure direction is safe: the HASHED_ASSET regex errs toward no-cache on misses (uppercase extensions, unhashed files under assets/ like Inter.ttf), so a false negative costs a revalidation rather than pinning a stale asset forever. Findings:

Nit — If-None-Match comparison is strict equality. ifNoneMatch === etag misses a multi-value header ("abc", "def") or *. Browsers echo the single stored value so this works in practice; a tolerant check is cheap insurance for proxies that rewrite or coalesce headers:

const matches = ifNoneMatch?.split(",").map((v) => v.trim()).includes(etag) ?? ifNoneMatch === "*"
if (matches) return HttpServerResponse.empty({ status: 304, headers })

Nit — 304 path does wasted work. embeddedUIResponse decodes the body to compute the CSP header for HTML before the etag check runs. On a no-cache revalidation of index.html — the most common 304 — the file is read, sha256'd, and fully decoded as UTF-8 for a response that discards everything except validators. Moving the etag check before the CSP computation (or computing CSP only for 200s) trims the hot path. Minor, since bodies are small.

FYI — bodies are re-read + re-hashed per request. fs.readFile + sha256 on every embedded request is fine at current asset sizes, but since embedded files are immutable for the life of the process, a (path → { body, etag }) memo would eliminate both the disk read and the hash entirely. Reasonable follow-up, not for this PR.

Verified the claim about scope: serveUIEffect only reaches serveEmbeddedUIEffect when embeddedWebUI is non-null, so the proxied app.opencode.ai path is genuinely untouched — upstream headers still pass through.

Verdict: approve — correct policy split, safe failure direction, good test coverage across all three file classes plus the conditional-request path.

cc @Hona @Brendonovich — could you review and approve? Fixes the stale-index.html-after-upgrade class behind the recurring "old UI pinned until Ctrl+F5" reports, and adds x-opencode-version as groundwork for #51860's version-mismatch UX.