[1/5] feat(router): model asynchronous worker lifecycle

[ashtonchew]

Summary

• Adds a typed client for the asynchronous SGLang Router worker lifecycle across the URL-identified 0.2.x API and UUID-identified 0.3.x API.
• Treats acceptance as the start of an operation: it waits for observable activation or absence and reconciles ambiguous outcomes before any retry.
• Introduces the control-plane contract without changing a runtime call site; PR #1804 integrates it with SGLang engines.

Context

The SGLang Model Gateway worker API queues worker registration and removal: a 202 Accepted response means that the background job was accepted, not that the worker is active or absent. A lost or malformed submission response is also ambiguous; immediately repeating the request can duplicate an operation that the router is already processing.

The recovery race reported in issue #1724 needs an observable publication boundary. This first layer isolates that router state machine so its version-specific identity handling, polling, and reconciliation can be reviewed independently from engine recovery.

Stack goal: This five-PR sequence addresses issue #1724: recovered updatable engines remain unroutable until actor-weight synchronization succeeds, and both rollout ingestion paths reject evidence that this invariant was violated.

Layer	Upstream PR	Status	Contract
1/5	#1801	Ready for review	Typed asynchronous Router lifecycle
2/5	#1804	Ready for review	Confirmed SGLang worker activation and removal
3/5	#1805	Ready for review	Recovered-engine publication after weight synchronization
4/5	#1806	Ready for review	Direct rollout published-weight guard
5/5	#1807	Ready for review	Session-ingress published-weight guard

All public drafts target main because external-fork branches cannot be selected as base refs in this repository. This matches the existing Miles external-stack convention: descendants appear cumulative until their parents merge, then GitHub removes shared commits from later diffs. Merge in order. If a parent is squash- or rebase-merged and commit identities change, rebase the descendants onto the updated main before continuing.

Description

• Validates worker requests, accepted-job responses, job status, and worker listings with explicit Pydantic models.
• Distinguishes definitive submission rejection, unknown submission outcome, and terminal background-job failure so callers can make different recovery decisions.
• Applies separate request timeouts and overall operation deadlines while polling accepted registration and removal jobs to an observable terminal state.
• Reconciles ambiguous registration and removal outcomes by worker identity without issuing duplicate control-plane requests.
• Supports URL worker identities used by Router 0.2.x and router-assigned UUID identities used by Router 0.3.x.

Validation

Layer checks

• pytest tests/fast/backends/sglang_utils/test_router_worker_client.py: 23 passed. The tests cover accepted jobs, terminal failures, ambiguous submissions, transient observations, idempotent removal, and both worker identity formats.
• Exact branch-head CPU CI passed all four Stage A shards and Stage B on b202e61f54.

Stack context

This PR does not change a runtime call site, so it does not make a standalone GPU claim. The controlled 8-B200 red/green test is documented in PR #1805, which owns the recovery ordering change. That test depends on the observable router activation boundary introduced here.

Risks and Follow-ups

The client accepts additional response fields but validates every field required by the supported 0.2.x and 0.3.x contracts. A future incompatible Router schema will require an explicit model update. Runtime behavior remains unchanged until the next layer adopts this client.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.