fix(ui): attached documents don't reach a Hub-installed flagship agent

[kovtcharov]

Attach a document to a chat session and ask about it, and a Hub-installed flagship agent answers as if the file were not there. The agent never sees it.

The Agent UI relays a sidecar turn over the agent's /query contract, and that request body carries the transcript and the session id but not the session's attached file paths. An in-process agent gets them through its constructor, so the same session behaves differently depending only on whether the agent was installed as a wheel or as a Hub binary.

Pre-existing for any binary install, but #4165 is what makes the path reachable for the flagship, so it will start being hit. Noted in a comment at the relay call site in _dispatch_sidecar_query.

Fixing it needs a decision first: whether the host sends paths the sidecar then indexes itself, or whether indexing stays host-side and the sidecar receives retrieved context. The second keeps the sidecar free of filesystem access it otherwise does not need.

Test plan

• Attach a PDF to a session and ask a question only answerable from it, against a binary-installed flagship
• Same session, same question, against a wheel install — the answers should not differ

[github-actions]

Two things from the code bear on the decision you flagged, plus a wrinkle that bites either option.

The "keeps the sidecar free of filesystem access" argument doesn't hold for the flagship. It already reads the user's disk — code search walks a project root, and it carries its own path allowlist and document config. Host-side retrieval wouldn't be withholding a capability it otherwise lacks; it'd leave the sidecar's own retrieval unused while the host does the same work separately.

Sending paths costs a contract bump, not just a field. The query body rejects unknown fields outright, so an already-installed binary would fail the whole turn rather than ignore the extra. That needs a version floor check on the host first — the email relay already has exactly that pattern to copy.

Either way, attaching a document mid-conversation still won't work. The sidecar builds a session's agent on the first turn and reuses it after, dropping the settings passed on later turns. So this needs a way to apply documents to a live session, not only at construction.

Worth a third test-plan line for that last one — attach on turn 3 of an existing session is the case a construction-time fix passes and users still hit.

🔍 Technical details

Sidecar already has the fields and the disk access. GaiaAgentConfig declares rag_documents (hub/agents/gaia/python/gaia_agent/agent.py:209) and allowed_paths (:220, defaulted to $HOME at :323), and the class composes CodeIndexToolsMixin (:246), which indexes a project root off disk. So option A is mostly plumbing into an existing config surface, and option B's isolation benefit is largely already spent for this agent.

Contract bump. QueryRequest inherits _Strict → ConfigDict(extra="forbid") (server.py:70-72), so an unknown rag_documents key is a 422, not a no-op. API_VERSION is currently 2.13 (server.py:60). Host-side gate to mirror: _EMAIL_QUERY_MIN_API_VERSION / _email_query_version_supported (src/gaia/ui/_chat_helpers.py:1009-1017) — the comment there records the pre-2.4 binary that passed the daemon's major-only handshake and then 404'd every /query.

Mid-session attachment. SessionRegistry.get_or_create returns existing and never applies config_kwargs to it (session_registry.py:179-182); kwargs only reach build_session_agent on the create path (:202). Today's only kwargs are model_id and ui_session_id (server.py:567-579), both constant per session, so nothing surfaces this — rag_documents is the first one that changes mid-session. Whichever way the decision lands, the live-session path needs its own handling (an update hook, or routing docs through the turn rather than the constructor). Host-side retrieval sidesteps it for free, since retrieved context rides the request body each turn.

In-process comparison, for parity checks: the host builds these via _compute_allowed_paths / _session_agent_kwargs (_chat_helpers.py:908, :958-993) from _resolve_rag_paths (:852) — note _compute_allowed_paths grants each document file, not its parent directory, so any path-forwarding design should preserve that narrowing rather than send a directory.