feat(tracing): stamp __commit_sha__ automatically when AGENT_COMMIT_SHA is set

[max-parke-scale]

When the process starts with AGENT_COMMIT_SHA set, __commit_sha__ is stamped onto SGP spans without any agent code. The agentex-agent chart is about to set that env var from a SHA-shaped image tag or an explicit global.agent.commitSha (scaleapi/sgp#5553, AGX1-969); with stamping gated on an explicit adk.code_revision.enable() call, that chart change would be a silent no-op for every agent that never opted in.

What changes

• code_revision resolves AGENT_COMMIT_SHA once at import and turns stamping on when it is set. Same SHA-shape guard as before: a non-commit value is refused with a warning and leaves stamping off.
• Only AGENT_COMMIT_SHA auto-enables. The AGENT_VERSION fallback stays behind an explicit enable() call, since deploys set AGENT_VERSION on every pod and it is an image tag on most paths.
• enable() and disable() keep working as before for agents that pass a value or want the fallback.

What does not change

No agent inherits the field by upgrading the SDK: with AGENT_COMMIT_SHA absent and no enable() call, nothing is stamped. That is the invariant #505 protected; the switch just moves from a code call to the env var the platform controls. The span-changes feed hoists __commit_sha__ to a top-level commit_sha (scaleapi#160082, OVE-916), so this is what makes that column non-empty.

Tests

test_code_revision.py: off with env absent, on from env at import, env set after import still needs enable(), bad env at import leaves it off; existing value-shape and fallback tests unchanged. Processor test renamed to assert the env-absent case. ruff and pyright clean; 59 tracing tests pass.

🧑‍💻🤖 — posted via Claude Code

Greptile Summary

Automatically enables validated source-commit stamping when AGENT_COMMIT_SHA is present during module import, while preserving explicit enable/disable behavior and keeping AGENT_VERSION opt-in.

• Adds an import-time environment activation hook.
• Updates environment-variable documentation.
• Expands tests for absent, valid, late, and invalid environment values.
• The startup regression test currently bypasses the import-time integration point it is intended to protect.

Confidence Score: 5/5

The implementation appears safe to merge; the remaining feedback is a non-blocking gap in regression coverage for the import-time hook.

Automatic stamping is gated on a present, validated AGENT_COMMIT_SHA, and no blocking behavioral or security defect was found. The tests should more directly protect the module-import side effect, but this coverage issue does not make the current implementation unsafe.

Files Needing Attention: tests/lib/core/tracing/test_code_revision.py

Important Files Changed

Filename	Overview
src/agentex/lib/core/tracing/code_revision.py	Adds import-time activation from AGENT_COMMIT_SHA while retaining validation and explicit controls.
src/agentex/lib/environment_variables.py	Updates the documented semantics of AGENT_COMMIT_SHA.
tests/lib/core/tracing/test_code_revision.py	Covers environment-based enablement states, but directly invokes the helper instead of testing the import-time integration point.
tests/lib/core/tracing/processors/test_sgp_tracing_processor.py	Updates the processor assertion to cover the environment-absent default.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Process starts] --> B[Import code_revision]
    B --> C{AGENT_COMMIT_SHA present?}
    C -->|No| D[Stamping remains disabled]
    C -->|Yes| E[Validate SHA shape]
    E -->|Valid| F[Enable __commit_sha__ stamping]
    E -->|Invalid| G[Warn and remain disabled]
    H[Explicit enable call] --> E
    I[Explicit disable call] --> D

Loading

Prompt To Fix All With AI

### Issue 1
tests/lib/core/tracing/test_code_revision.py:38
**Startup Path Is Untested**

Calling `_enable_from_environment()` directly verifies the helper but bypasses the module-level call that provides the new startup behavior. These tests would still pass if that import-time call were removed, leaving `AGENT_COMMIT_SHA` set at process startup without enabling commit stamping. Exercise this case through a fresh module import or an isolated subprocess.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (2): Last reviewed commit: "feat(tracing): stamp __commit_sha__ auto..." | Re-trigger Greptile}

Context used (3)

• Knowledge Base — Observability
• Knowledge Base — Tracing pipeline
• Knowledge Base — Testing and compatibility