feat: forward engine routing (incl. namespace pools) via ClientOptions.environment (ENG-2612)

[ziollek]

Summary

Add an optional environment mapping to ClientOptions and send it verbatim as the environment field of the session request body when set. This lets a caller steer a session to a non-default engine target — most importantly a namespace pool — e.g.:

# Preferred: route to an engine namespace pool (fans out across replicas)
ClientOptions(environment={"namespace": "devspace-release-e2e"})

# Also supported: pin to one exact pod, or a version
ClientOptions(environment={"podName": "anam-engine-..."})
ClientOptions(environment={"engineVersion": "v5.13.2"})

Why namespace routing (the primary use case)

The backend accepts three targeting keys with precedence namespace > podName > engineVersion (anam-lab session route → X-Anam-Target-Namespace / X-Anam-Target-Pod / X-Anam-Engine-Version):

• namespace targets an engine namespace pool (anam-engine-preview-<n> or devspace-<name>). The coordinator fans each session out to any ready worker in that namespace, so it scales with the number of engine replicas and survives a pod restart mid-run.
• podName single-hops to one exact pod with no fan-out — a single replica serves one session, so a 2nd concurrent session gets 503 "No personas available".

release-e2e (ENG-2612) deploys the engine into devspace-release-e2e and routes by namespace for exactly this reason. This PR is what lets the python SDK carry that key — it previously had no way to, so the harness raised RuntimeError: ClientOptions.environment is required for ANAM_* routing overrides.

This is not a new routing capability — the backend already honours the environment object; the browser/JS path injects it into the session-token request today. This PR gives the direct API-key path a first-class, routing-key-agnostic way to send the same field.

Changes

• ClientOptions.environment: dict[str, str] | None = None (documented; namespace / podName / engineVersion).
• CoreApiClient.start_session adds body["environment"] only when set — omitted entirely for production, so no behaviour change for existing callers.
• Tests: option round-trips; body includes environment when set and omits it when unset.

Because the dict is forwarded verbatim, no key-specific code is needed — namespace, podName, and engineVersion all pass through unchanged (verified against the direct POST /v1/engine/session schema, which accepts environment.namespace).

Validation

• pytest -q — 63 passed
• ruff check / ruff format --check — clean
• mypy src/anam/_api.py src/anam/types.py — clean

Follow-up

After this merges + is tagged, bump the python-sdk pin in anam-org/e2e-tests (currently v0.5.0-alpha.2) so the release-e2e python_sdk / passthrough scenarios route to the deployed namespace pool.

🤖 Generated with Claude Code

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}