fix(vapi): resolve versioned credentials for observability polling - #3704

Summary

Repair the product prerequisite blocking future-agi/docs#1090. Keep that guide on hold until this fix has been reviewed, merged by Nikhil and deployed.

• Resolve Vapi polling credentials from the active agent version, falling back to the latest version only when none is active, through the existing resolve_api_key_for_version reader. This is the same selection used by Vapi recording downloads.
• Preserve the canonical encrypted legacy-credential fallback. Use the old plaintext AgentDefinition.api_key column only for agents with no versions; never override a configured version with a stale column.
• Fail missing agent/key/assistant configuration and decryption failures before HTTP or watermark advancement. A successful empty response still advances the window. Other providers' credential resolution and Vapi pagination are unchanged.

Regression proof

On unchanged product dev 42f1fe1f098fb5dec2081a242f532b22df26bf52, the final regression tests produce 13 failures, 1 pass. New hosted connections return no calls without HTTP; after rotation the old legacy key is still sent and the synthetic revoked-key response fails. Missing configuration is incorrectly treated as a completed polling window.

After the repair, 407 tests pass, including:

• Real hosted-creation API, persisted encrypted ProviderCredentials, credential-change service, preflight/default activation, and Vapi polling. Both a null legacy column and a stale legacy column are exercised; the old synthetic key is revoked after rotation. External preflight, provider HTTP and workflow start are mocked by the existing fixtures. No actual environment build or provider call is claimed.
• Twelve polling regressions covering active versus draft/latest selection, canonical encrypted legacy fallback, pre-versioning agents, missing configuration, decryption errors, HTTP auth failure, empty success, and the scheduling wrapper's storage/watermark boundary.
• Complete existing provider, hosted-creation, Retell orchestration, Vapi recording and normalization suites.

Re-run from futureagi/ with the normal disposable test services/settings:

pytest tracer/tests/test_vapi_polling_credentials.py tracer/tests/test_observability_providers.py tracer/tests/test_observability_livekit_skip.py tracer/tests/test_pull_observability_bland_twilio.py tracer/tests/test_retell_poll_orchestration.py tracer/tests/test_vapi_recording_service.py tracer/tests/test_vapi_process_raw_logs.py tracer/tests/test_vapi_recording_urls.py simulate/tests/test_harness_agent_creation.py -q

Local runs used owned disposable PostgreSQL 16, synthetic credentials and an outbound-network-denied sandbox. No Cloud/customer credentials or live Vapi calls. Ruff lint and formatting pass on all four changed files; the existing touched files also passed on the base. No migration, serializer, API contract, frontend or dependency changes.

AI use: Claude Code using gpt-6-astra implemented the repair and regression tests and ran the checks described above; independent review is still required.
E2E: exempt (backend-internal)

E2E coverage

The exact committed diff passes the repository gate: EXEMPT, no pinned flows hit. The explicit marker above also satisfies the admission template. The dominant exemption is tests-only; the production service file itself is classified backend-internal. This is not a claim of browser E2E coverage. Hosted Vapi service/credential lifecycle is tested against real PostgreSQL with inert external boundaries; no browser/real-provider flow was run.

Admission

The admission workflow also requires a linked maintainer-accepted issue for this four-file repair. The defect was assigned from the docs #1090 independent review, not from an accepted GitHub issue; the open Vapi issue search found no matching accepted issue. That maintainer admission decision remains outstanding. No unrelated issue is linked and no acceptance is claimed.

Rollout

No schema or package release. Deploy the backend/polling worker after normal product review; the product PR must be merged by Nikhil, not the integration automation. Previously skipped historical windows are not automatically replayed by this change. The docs release hold remains until the product prerequisite is deployed.

🤖 Generated with Claude Code