feat(splunk-ao-adk): rename LogStream → AgentStream env var (HYBIM-914)

[shuningc]

Summary

• Renames the SPLUNK_AO_LOG_STREAM environment variable to SPLUNK_AO_AGENT_STREAM in splunk-ao-adk, aligning it with the rename already applied to the core SDK, a2a, and examples in feat: hard cut-over — rename LogStream→AgentStream, Metric→Evaluator #100
• Updates SplunkAOADKCallback and SplunkAOADKPlugin to read from SPLUNK_AO_AGENT_STREAM
• Pins opentelemetry-resourcedetector-gcp==1.12.0a0 as a dev dependency to unblock uv sync — 1.13.0 (the only stable release satisfying google-adk's requirement) was yanked; all other available versions are
  pre-releases and require explicit opt-in

Test plan

• uv sync --dev resolves successfully in splunk-ao-adk/
• uv run pytest passes in splunk-ao-adk/
• Confirm SPLUNK_AO_AGENT_STREAM env var is picked up correctly by both SplunkAOADKCallback and SplunkAOADKPlugin

[fercor-cisco]

🤖 This review was generated by the Astra agent (claude-opus-4-8). It may contain mistakes.

Verdict: needs_discussion — Rename is complete and correct, but the ADK package hard-cuts the old env var while the core SDK it depends on still honors it as a deprecated alias — an inconsistency the ticket explicitly flags as an open decision.

General Comments

• 🟠 major (design): This PR hard-cuts SPLUNK_AO_LOG_STREAM in the ADK package (only SPLUNK_AO_AGENT_STREAM is read/validated), but the core splunk-ao SDK this package depends on keeps SPLUNK_AO_LOG_STREAM as an explicit deprecated alias — see src/splunk_ao/config.py:58 (("SPLUNK_AO_LOG_STREAM", "GALILEO_LOG_STREAM") # deprecated alias) and src/splunk_ao/utils/env_helpers.py:74/112/125 (getenv("SPLUNK_AO_AGENT_STREAM") or getenv("SPLUNK_AO_LOG_STREAM")). The result is inconsistent behavior for a user who has only the old var set: the ADK __init__ validation raises ValueError, even though the underlying SDK resolution path would have accepted it. HYBIM-914 explicitly leaves this as a decision ("whether to hard-cut ... or provide a deprecation warning" / "a backward compatibility alias should be considered"). Please confirm the intent — either match the SDK's backward-compat alias here, or document/accept that the ADK integration is a hard cut that diverges from the SDK. This should be resolved before merge to avoid confusing upgrade behavior.

[fercor-cisco]

🟡 minor (other): Pinning a pre-release (==1.12.0a0) as a workaround for the yanked 1.13.0 is reasonable to unblock uv sync, but an exact alpha pin will silently rot: once a non-yanked stable release satisfying google-adk lands, this pin will hold the resolver back and no one will notice. Consider adding a # TODO/tracking-issue reference next to it so it gets revisited, and confirm 1.12.0a0 actually satisfies google-adk's constraint on this dependency (the PR body says 1.13.0 was the stable version that satisfied it).

🤖 Generated by the Astra agent

[fercor-cisco]

Dug into this and tested resolution directly (uv 0.11.17, dry-run uv lock against PyPI). Findings, with a correction to my own earlier reasoning:

The exact pin is no longer necessary. With the line removed entirely, resolution succeeds and uv auto-selects 1.12.0a0:

Scenario	Result
pin removed	✅ Resolved 147 packages — uv picks 1.12.0a0 on its own
==1.12.0a0	✅ resolves

Why: uv treats yanked 1.13.0 as not available, so for opentelemetry-resourcedetector-gcp every available version is a pre-release → uv's default if-necessary prerelease strategy kicks in and allows the alpha. So the yank actually enables the fallback. The pin was almost certainly a real fix when it was added (before 1.13.0 was yanked, a stable release existed, if-necessary didn't trigger, and uv sync failed) — but that condition is now gone.

Suggested change — replace the exact pin with an explicit-marker range:

# google-adk needs this GCP detector, whose only stable release (1.13.0) is
# yanked; the a0 marker opts into the pre-release line. Drop when a non-yanked
# stable satisfies google-adk.
"opentelemetry-resourcedetector-gcp>=1.12.0a0",

The a0 marker opts just this package into pre-releases regardless of yank state (so it survives 1.13.0 being un-yanked), and the range lets uv move up to any future non-yanked stable automatically — no rot, no TODO needed. Simply deleting the line also works today but silently depends on the yank staying in place.

Second point confirmed: 1.12.0a0 satisfies the constraint — uv tree --invert shows google-adk v1.36.2 pulling it in transitively (directly and via google-cloud-spanner, the GCP OTel exporters, etc.).

[shuningc]

Done

[adityamehra]

Multi-Model Review: PR #141 — feat(splunk-ao-adk): rename LogStream → AgentStream env var

Reviewers: Claude (Opus) · Codex (GPT) · Cursor (Gemini) · Judge: Claude (Sonnet)
Updated to reflect fercor-cisco's explicit team decision: backward compat with SPLUNK_AO_LOG_STREAM is intentionally not supported in the ADK.

---

Overall Verdict: ✅ Approved with suggestions

The rename is mechanically complete (all 18 occurrences covered). The opentelemetry-resourcedetector-gcp==1.12.0a0 alpha pin is correct and necessary (1.13.0 is yanked on PyPI with "breaks imports"). The team has explicitly confirmed the hard cutover is intentional — no backward compat needed.

Two minor items remain:

---

🟡 MEDIUM — Add a test locking in the intentional hard-cutover behavior

Files: splunk-ao-adk/tests/test_callback.py, tests/test_plugin.py

Since the hard cutover is a deliberate design choice (confirmed by @fercor-cisco), it should be locked in with an explicit test. Without it, a future contributor could accidentally add backward compat and there would be no regression guard — and no documentation of the intent.

Suggested test for both test_callback.py and test_plugin.py:

def test_old_env_var_not_recognized(self, monkeypatch):
    """SPLUNK_AO_LOG_STREAM (old name) is intentionally not supported; SPLUNK_AO_AGENT_STREAM required."""
    monkeypatch.setenv("SPLUNK_AO_LOG_STREAM", "some-stream")
    monkeypatch.delenv("SPLUNK_AO_AGENT_STREAM", raising=False)
    with pytest.raises(ValueError, match="SPLUNK_AO_AGENT_STREAM"):
        SplunkAOADKCallback(project="my-project")

---

⚪ NIT — Test isolation: clean up SPLUNK_AO_LOG_STREAM in the "requires" test cases

Files: test_callback.py, test_plugin.py

Tests asserting ValueError on missing config only delenv("SPLUNK_AO_AGENT_STREAM"). A developer running with SPLUNK_AO_LOG_STREAM in their shell during the migration period could get unexpected results. Add cleanup for isolation:

monkeypatch.delenv("SPLUNK_AO_AGENT_STREAM", raising=False)
monkeypatch.delenv("SPLUNK_AO_LOG_STREAM", raising=False)  # not supported; ensure test isolation

---

✅ Resolved / Not an issue

Finding	Verdict
Hard cutover breaks old SPLUNK_AO_LOG_STREAM users	Resolved — fercor-cisco confirmed hard cutover is intentional; no backward compat needed
opentelemetry-resourcedetector-gcp==1.12.0a0 alpha pin	Not an issue — 1.13.0 yanked ("breaks imports"); alpha is the only viable version
Core SDK still reads old name (Codex)	False positive — origin/main has full backward compat; Codex browsed local branch
"Split-read bug" (Cursor)	False positive — SplunkAOObserver re-resolves via env_helpers which reads new name correctly
Stale docstrings (Cursor)	False positive — diff covers all 6 occurrences across both files
Alpha pin malformed in pyproject.toml (Cursor)	False positive — correctly placed inside [dependency-groups] dev

[fercor-cisco]

We do not need to support fallback or backward compatibility with SPLUNK_AO_LOG_STREAM.