Fix: restore event round trip in VertexAiSessionService

[AmaadMartin]

Please ensure you have read the contribution guide before creating a pull request.

Link to Issue or Description of Change

1. Link to an existing issue (if applicable):

• N/A

2. Or, if no issue exists, describe the change:

Problem:

Four independent defects in VertexAiSessionService break the appendEvent() -> getSession() round trip on the legacy (non-rawEvent) read path and make the write path unsafe. adk-python already handles all four correctly.

1. groundingMetadata is written but never restored. appendEvent copies it into config.eventMetadata, but the legacy branch of _fromApiEvent never reads it back, so a replayed event always comes back with groundingMetadata === undefined.
2. Write/read naming asymmetry on the agent-transfer action. appendEvent copied event.actions verbatim, so the wire payload carried ADK's transferToAgent, while the read path looks for transferAgent (the name the API's EventActions declares, and the camelCase form of the transfer_agent field adk-python writes). The two names never met, so an agent transfer written by adk-js was silently dropped when the session was replayed through the legacy path.
3. The rawEvent fallback caught everything. The append was wrapped in an undiscriminated try/catch that retried on any throw. A transient failure (5xx, 429, timeout, socket reset) that may already have persisted the event triggered a second appendEvent, duplicating it in the session, and callers saw the failure of the retry rather than of the first attempt. It also rebuilt the request, so the retry could carry a different inv-${Date.now()} invocation id than the first attempt.
4. partMetadata was not stripped before append. partMetadata is a Gemini Developer API-only Part field that adk-js populates for streamed/partial parts; the Agent Engine Sessions API rejects it with 400 INVALID_ARGUMENT (Unknown name "part_metadata" at 'event.content.parts[0]').

Solution:

All four fixes live in core/src/sessions/vertex_ai_session_service.ts; the service is @experimental, so the wire-format corrections are in scope. No new dependency, no new export, no signature change.

• _fromApiEvent now restores groundingMetadata from eventMetadata — a direct property read, since the two @google/genai copies in the tree declare a structurally compatible GroundingMetadata, so no cast is needed.
• appendEvent emits the transfer action as actions.transferAgent via a small toApiEventActions mapper; every other action field, including requestedToolConfirmations, keeps its name. The read path maps transferAgent back to Event.actions.transferToAgent and still accepts a legacy transferToAgent key: the released write path copied event.actions onto the request verbatim and the SDK converter forwards that object unchanged, so already-stored sessions can carry the ADK key and dropping the fallback would silently lose their transfers.
• The rawEvent retry is now gated on the service rejecting the payload itself (HTTP 400), which is what an API that does not know rawEvent returns. This is a deliberate behaviour change: transient failures now propagate unchanged instead of being quietly re-appended. The error is matched structurally on status rather than with instanceof ApiError, because core and @google-cloud/vertexai resolve separate @google/genai copies and instanceof is false at runtime. The retry also reuses the already-built request, so both attempts share the same name, author, invocationId and timestamp and differ only in rawEvent.
• appendEvent strips partMetadata from every Part in both config.content and config.rawEvent.content, building a copy so the caller's event is never mutated (partialCopy shares content by reference, so stripping in place would corrupt the caller's event).

Compatibility: new writes emit actions.transferAgent and omit partMetadata, aligning adk-js with adk-python and with the API's declared schema. Old data keeps working because the read path accepts both action key names.

Testing Plan

Unit Tests:

• I have added or updated unit tests for my change.
• All unit tests pass locally.

Added to core/test/sessions/vertex_ai_session_service_test.ts, reusing the existing mock Sessions fixture and the createEvent / createEventActions / createSession factories (the append mock is typed with the SDK's request-parameter type, so the captured payload is checked by the compiler rather than cast):

• sends transferToAgent as transferAgent and keeps every other action — asserts the entire captured config.actions, which pins both the rename and the absence of a transferToAgent key, and guards requestedToolConfirmations, which the SDK type omits so the compiler cannot catch its loss.
• strips partMetadata from content and rawEvent without mutating the event, handles content without parts, handles an event without content.
• retries without rawEvent when the API rejects it with 400 — records what each attempt actually carried and asserts the retry reuses the same request object (which is what keeps the invocation id and timestamp identical; the previous code minted a fresh one).
• rethrows a server error / a network error without re-appending — the regression guard for the duplicate append, asserting exactly one call.
• restores groundingMetadata from eventMetadata, restores transferToAgent from actions.transferAgent, restores transferToAgent from a legacy transferToAgent key.

Commands run locally on the pushed commit:

• npx vitest run --project unit:core core/test/sessions/vertex_ai_session_service_test.ts — 61 passed.
• Coverage of the changed file (--coverage.include='core/src/sessions/vertex_ai_session_service.ts'): every new line and branch is executed; the only uncovered branches in the file are pre-existing ones this change does not touch.
• npm run build, npm run lint, npm run format:check — all pass.

Manual End-to-End (E2E) Tests:

The Agent Engine Sessions backend cannot be exercised in CI, so this needs a real Vertex AI project with an Agent Engine. With projectId / location / agentEngineId pointed at a live reasoning engine:

1. createSession, then appendEvent with an event that carries actions.transferToAgent, a groundingMetadata payload, and a part with partMetadata set.
2. Confirm the append succeeds — before this change the partMetadata part fails with 400 INVALID_ARGUMENT (Unknown name "part_metadata").
3. getSession and confirm the event comes back with actions.transferToAgent and groundingMetadata intact, and with the part's text preserved (partMetadata is intentionally not persisted, matching adk-python).

Checklist

• I have read the CONTRIBUTING.md document.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have added tests that prove my fix is effective or that my feature works.
• New and existing unit tests pass locally with my changes.
• I have manually tested my changes end-to-end.
• Any dependent changes have been merged and published in downstream modules.

Additional context

The service is marked @experimental, so the wire-format corrections (emitting actions.transferAgent, omitting partMetadata) are in scope. The read path stays backward compatible with sessions written by earlier adk-js versions.