RFC: Automated toolchain version monitoring and upgrade workflow

[scottschreckengaust]

Problem

Several runtime dependencies in the agent Dockerfile and pyproject.toml are manually pinned with no automated notification when new versions are available:

Dependency	Current Pin	Update Frequency	Risk of Stale
Node.js	setup_24.x (LTS)	~6 months (LTS cycle)	Medium
Claude Code CLI	@anthropic-ai/claude-code@2.1.142	Weekly+	High
claude-agent-sdk	claude-agent-sdk==0.2.82	Weekly+ (bundles CLI)	High
boto3	boto3==1.43.6	Weekly (AWS SDK releases)	High
Go (gh builder)	golang:1.26.3-bookworm	~6 months	Low
gh CLI	GH_VERSION=2.92.0	Monthly	Low
Python base	python:3.13-slim	~12 months	Low
uv	ghcr.io/astral-sh/uv:0.11.14	Multiple times/week	Medium

Key coupling: claude-agent-sdk ↔ Claude Code CLI

The claude-agent-sdk Python package bundles the Claude Code CLI binary inside its wheel. The Dockerfile also installs the CLI separately via npm. These versions must stay in sync:

• pyproject.toml: claude-agent-sdk==0.2.82 → bundles CLI 2.1.142
• Dockerfile: @anthropic-ai/claude-code@2.1.142

When upgrading either, check the SDK release notes to find which CLI version it bundles, then update both.

boto3 releases frequently

AWS releases boto3 multiple times per week. Each release adds new service APIs and bug fixes. Falling behind risks missing security patches and new features needed for AgentCore/Bedrock.

Proposal

Option A: Dependabot (recommended)

Dependabot is GitHub-native (no license concerns) and covers the ecosystems that matter most:

Ecosystem	Directory	What it monitors	Value
github-actions	/.github/workflows/	SHA-pinned action versions (7 actions)	Highest — nothing else does this
docker	/agent/	FROM image tags (golang, python)	High — Trivy flags CVEs but doesn't propose base-image bumps
npm	/	Yarn workspace dependencies	Moderate — osv-scanner/Retire cover CVEs but not freshness
pip	/agent/	pyproject.toml + uv.lock (supported)	High — covers boto3, claude-agent-sdk, fastapi, etc.

Option B: Scheduled GitHub Action (for Dockerfile pin gaps)

Dependabot cannot parse version strings inside RUN commands or ARG values. A weekly Action would cover:

1. Claude Code CLI: compare @anthropic-ai/claude-code@X vs npm view @anthropic-ai/claude-code version
2. claude-agent-sdk: compare pinned vs latest SDK release and extract bundled CLI version
3. gh CLI: compare GH_VERSION ARG vs latest cli/cli release
4. uv: compare pinned COPY tag vs latest astral-sh/uv release
5. Opens an issue when versions drift, noting the coupling between SDK and CLI

What each tool covers

Dependency	Dependabot?	Custom Action?	Notes
claude-agent-sdk	Yes (pip)	Yes (coupling check)	Dependabot bumps the pin; Action verifies CLI alignment
Claude Code CLI (Dockerfile)	No	Yes	Inside RUN command, not parseable
boto3	Yes (pip)	No	Standard Dependabot pip coverage
Node.js (Dockerfile)	No	Possible	Inside curl command, not parseable
Go builder image	Yes (docker)	No	FROM golang:X tag
Python base image	Yes (docker)	No	FROM python:X tag
gh CLI (ARG)	No	Yes	ARG GH_VERSION=X not parseable
uv (COPY --from)	Yes (docker)	No	COPY --from=ghcr.io/astral-sh/uv:X is a docker ref
GitHub Actions	Yes (github-actions)	No	SHA pins auto-bumped
npm deps (CDK, CLI, docs)	Yes (npm)	No	Yarn workspace coverage

Implementation Plan

• Add .github/dependabot.yml with github-actions, docker, npm, and pip ecosystems
• Configure grouping (e.g., group minor/patch boto3 updates, group AWS SDK updates)
• Set open-pull-requests-limit per ecosystem to manage PR noise
• Create scheduled Action for Dockerfile pin monitoring (Claude Code CLI ↔ SDK coupling, gh, Node)
• Document the SDK ↔ CLI coupling in AGENTS.md or CONTRIBUTING.md

Related Issues

• chore(agent): upgrade Python 3.13 → 3.14 #105 — Upgrade Python 3.13 → 3.14
• chore(agent): upgrade Debian base from bookworm to trixie #106 — Upgrade Debian bookworm → trixie
• PR chore(agent): upgrade runtime deps — Node 24, Claude SDK 0.2.82, pin all Python deps #103 — Node.js 20→24, Claude Code 2.1.142, pin uv 0.11.14, claude-agent-sdk 0.2.82

References

• Node.js release schedule
• claude-agent-sdk releases
• Dependabot Docker support
• Dependabot GitHub Actions support
• Dependabot pip/uv.lock support