fix(ui): cite chat attachments by their own name - #6896

Summary

Answers about a file attached with the + button now cite the file's own name instead of GAIA's internal upload ID: According to kestrel-plan.pdf, page 1: rather than According to f27f4885-cec8-4161-9dbd-ebc8a3c25005.pdf, page 1:.

Why

The agent only ever saw the upload copy's random name, so that's what it cited, and users couldn't tell which file an answer came from.

Linked issue

Closes #5183

Changes

• Adds src/gaia/upload_names.py, the one place that knows the naming. Attachments are stored as <12 hex>_<name><ext>, and the prefix is removed for display only when the file is directly inside chat/uploads.
• upload_file uses the new name. /api/files/upload still returns filename, original_name and url, but filename is no longer a UUID.
• query_specific_file cites the readable name in its instruction and messages. file and source_files keep the exact path, so the file can still be opened.
• The chunk cards and the "Indexed ..." step label use the readable name.

Decisions to check

• Not _sanitize_stem: the triage comment suggested reusing it from documents.py, but it keeps spaces and parentheses. UPLOAD_LINK_RE stops at a space or ), and UPLOAD_URL_RE in markdown.ts only serves ASCII letters, digits, ., _ and -, so Q3 plan (final).pdf would stop working as a link. This keeps only those characters.
• Prefix, not suffix: the name always starts with a hex character, which UPLOAD_URL_RE requires. <uuid>.pdf copies from before this change don't match, so they keep their full name.
• Random ID length: 48 bits instead of the UUID's 122, the same as managed documents.

Limits

• Spaces and punctuation become _, so Q3 plan (final).pdf is cited as Q3_plan_final.pdf.
• A name with no ASCII letters or digits is cited as attachment.pdf. The original name still appears on the link and in the turn summary.
• query_documents still asks for the full path, as it does for every document. That path now ends in a readable name, with the prefix.
• Uploads made before this change keep their UUID names.

Test plan

Run in a clean python:3.12-slim container, with .[ui] and the test tools installed:

• pytest tests/unit/chat/ui/test_upload_names.py tests/unit/chat/ui/test_upload_links.py tests/unit/chat/ui/test_attachment_scope.py tests/unit/chat/ui/test_upload_serving.py tests/unit/chat/ui/test_media_upload.py tests/unit/chat/ui/test_sse_handler.py tests/unit/chat/ui/test_turn_summary.py tests/unit/test_rag_citation_instruction.py tests/unit/test_rag_file_resolution.py tests/integration/test_files_router.py: 604 passed, 1 skipped.
• black --check and isort --check-only on the changed files: clean.
• Full pytest tests/unit: 35,021 passed. It was run with .[ui] only and without git history, so it also had 96 failures and 523 errors. Many were missing test tools. I reran the 95 affected test files with those tools installed: 25 failures, none in the files this PR changes. Most also fail on main, and the rest need git history, which my container's copy didn't have.

Not run: python util/lint.py --all, the web UI tests, and a real model. The last means this confirms the instruction sent to the model, not a model's actual answer.

Evidence

The same upload and query_specific_file steps, on main and on this branch:

The step label changes from Indexed <uploads>/368b4401-….txt (1 chunks) to Indexed kestrel-plan.txt (1 chunks). On both versions, every file still resolves through the agent's link handling and matches UPLOAD_URL_RE.

• Agent exposed in the Agent UI: N/A, no agent changes. The citation and step label are covered by the evidence above, without a running UI or model.
• MCP tools / servers: N/A
• CLI: N/A
• HTTP API / REST: /api/files/upload returns the new filename form, shown above.

Checklist

• I have linked a GitHub issue above (Closes #N / Fixes #N / Refs #N).
• I have described why this change is being made, not just what changed.
• I have run linting and tests locally (python util/lint.py --all, pytest tests/unit/). Partly: black, isort and pytest tests/unit/ as described above, not util/lint.py.
• I have attached real-world evidence matched to the surface I changed (see Evidence above), or marked each surface N/A.
• I have updated documentation if user-visible behavior changed (see CONTRIBUTING.md). N/A: I found no docs describing the upload file name.