`sf agent preview` fails with `AgentApiNotFound` against staging (aws-stage1) orgs — `stage.api.salesforce.com` missing from endpoint fallback

[atulkc]

Summary

sf agent preview (and any command routed through requestWithEndpointFallback in @salesforce/agents) cannot reach any agent on an org served by the stage.api.salesforce.com SFAP gateway (falcon instance aws-stage1). The fallback only tries api., test.api., and dev.api.salesforce.com, so requests to those orgs 404 on every attempt and the CLI then throws AgentApiNotFound, whose message tells the user to check permissions — sending everyone down the wrong path. The real cause is a routing 404: the request never reaches the Agent API backend.

Steps To Reproduce

1. Authenticate to an org whose My Domain resolves to a pod on the aws-stage1-useast2 falcon instance (SFAP gateway stage.api.salesforce.com).
2. Run sf agent preview -o <that-org> -n <AgentApiName>.
3. The session fails to start.

(Repro requires an internal aws-stage1 staging org, so a public sample repo isn't applicable — the failure is host-routing, not project-specific. Happy to provide org details privately to a maintainer.)

Expected result

The preview session starts, the same way it does for prod / test. / dev. orgs, and the same way the agent already previews successfully in the Agent Builder UI (which routes internally through stage.api.salesforce.com).

Actual result

Error (AgentApiNotFound): Unable to access the Salesforce Agent APIs. Ensure the
user '<user>' has the necessary permissions and authorization to perform this action.

Additional information

Root cause (verified):

• The session-create call is POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{botId}/sessions.
• requestWithEndpointFallback (src/utils.ts) rewrites the host across ['', 'test.', 'dev.'] on each 404 → api., test.api., dev.api.salesforce.com.
• The org's actual SFAP/Hawking gateway is stage.api.salesforce.com (confirmed from the org's GatewayHawkingInfo: endpoint=https://stage.api.salesforce.com, falconInstance=aws-stage1-useast2).
• Backend logs confirm the CLI's request (identified by its generated externalSessionKey) never reaches the Agent API service — it 404s at the public edge because none of the attempted hosts map to the aws-stage1 backend. The AgentApiNotFound message therefore misattributes a pure HTTP 404 to a permissions problem.

Suggested fix: add 'stage.' to the fallback list (and the host-matching regex) in requestWithEndpointFallback. PR incoming.

Secondary (optional): even after the host fix, consider having the AgentApiNotFound message state that all Agent API endpoints returned 404 and list attemptedEndpoints, so routing failures aren't misdiagnosed as authorization failures.

System Information

Shell: zsh (macOS)

{
  "cliVersion": "@salesforce/cli/2.150.6",
  "architecture": "darwin-arm64",
  "nodeVersion": "node-v24.18.0",
  "osVersion": "Darwin 25.6.0",
  "shell": "zsh",
  "pluginVersions": ["agent 2.0.5 (core)"],
  "dependency": "@salesforce/agents 2.2.0"
}

[iowillhoit]

Hey @atulkc, I've passed this along to the owning team. Thanks for reporting the issue and providing a PR 🙌

[github-actions]

We have determined that the issue you reported exists in code owned by another team that uses only the official support channels. To ensure that your issue is addressed, open an official Salesforce customer support ticket with a link to this issue. We encourage anyone experiencing this issue to do the same to increase the priority. We will keep this issue open for the community to collaborate on.