[ext-agents] `azd ai agent files upload` takes the file as the positional arg, hangs on ambiguous agent in multi-service projects

[therealjohn]

Summary

azd ai agent files upload binds its positional argument to the file path ([file]), while the sibling command azd ai agent invoke binds its positional to the agent name ([agent]). Users -- and LLMs reading the help text -- mirror the invoke pattern and run files upload <agent> -f <file>, which silently binds <agent> to the file path. With multiple azure.ai.agent services declared and no -n/--agent-name, the agent is ambiguous and the command renders the interactive picker, which hangs silently in non-TTY contexts (see #8584).

Repro

Multi-service project (>= 2 azure.ai.agent services), deployed remote agent:

azd ai agent files upload my-agent -f ./contract.txt

Observed

Hangs indefinitely (observed ~12 minutes before a manual kill) with no output, no spinner, no CPU activity. pstree / wchan shows the extension child (azure-ai-agents-... files upload my-agent -f ./contract.txt) blocked in do_epoll_wait on the local gRPC pipe back to the parent azd; no Azure sockets are ever opened. The extension has rendered a service picker into a stdout that is piped, so it is invisible. Sending Enter does nothing; only Ctrl+C recovers.

Root cause: my-agent is bound to the file positional, so the agent name has to come from -n/--agent-name. With multiple services and no -n, auto-detect fails and the picker fires.

Correct invocation (works, ~2s)

azd ai agent files upload -f ./contract.txt -n my-agent

Expected

• Smallest fix: when the files upload positional resolves to a path that does not exist but matches an agent name in azure.yaml, fail fast with a hint:
  did you mean: azd ai agent files upload -n my-agent -f <file>?
  instead of falling through to "auto-detect agent (failed) -> render picker".
• Better: make the agent the positional for files upload too, for consistency with invoke.
• See also [ext-agents] Interactive agent-service picker hangs silently in non-TTY contexts instead of failing fast #8584 -- the non-TTY picker hang that turns this mistake into a silent multi-minute block.

Impact

Tooling that wraps azd ai agent files upload (CI pipelines, agent harnesses, runbooks) hangs forever with no diagnosable signal. The correct flag form works in ~2s; the trap is purely the flipped positional plus the silent picker.

Environment

• azd 1.25.4; azure.ai.agents 0.1.36-preview (also reproduced on 0.1.38-preview)
• Linux (Ubuntu via WSL2)
• Project shape: 1 root azure.yaml, 6 azure.ai.agent service blocks, shared .azure/<env>/