feat(agent): let promote target a deployment other than production

[JackNDwyer]

What

lk agent promote --from dev --to qa

Production stays the default, so lk agent promote --deployment staging behaves exactly as before.

Why this is CLI-only

The destination was never hardcoded in the backend. cmd/lk/agent.go just always passed "":

agentsClient.PromoteAgent(ctx, agentID, agentDeployment, "")

Everything underneath already supports an arbitrary destination:

• PromoteAgentRequest has both src_deployment and dst_deployment (protocol/protobufs/livekit_cloud_agent.proto:84-88)
• the SDK passes both through (server-sdk-go/pkg/cloudagents/client.go:176-186)
• cloud-agents pkg/server/agent_server_v2.go:21-164 validates both names, rejects production as source, canonicalizes the deprecated "production" literal to "", rejects src equal to dst, requires both region agents to exist and be non-deleted, requires the source version to be Available, then calls SetActiveVersion(..., req.DstDeployment), reusing the existing immutable version with no rebuild

Flags

• --from is the documented spelling for the source
• --deployment / -d still work as an alias, so existing scripts are unaffected. Passing both with different values is an error rather than a silent precedence rule
• --to defaults to empty, which the API reads as production

Behavior worth knowing

• Destination must already exist. The server returns destination deployment not found. Auto-creating it would need the deploy path for namespace and quota, so it is deliberately out of scope here.
• Quota: the deployment-count quota is not re-checked, since the destination pre-exists. The version quota is enforced in SetActiveVersion and surfaces as ResourceExhausted.
• Drain: promotion sets the active version on the destination, so it follows that deployment's semantics. Promoting into a non-production deployment drops its active sessions immediately; promoting into production drains.
• Idempotency: promoting when the destination already points at that version re-sets it and re-schedules. A follow-up could short-circuit when dstRegionAgent.VersionID == srcRegionAgent.VersionID.

Tests

TestResolvePromoteSource covers --from, the --deployment and -d fallbacks, agreeing and conflicting combinations, and neither being set. TestPromoteDestinationDefaultsToProduction pins the default. Both pass locally.

🤖 Generated with Claude Code

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}