`agent publish authoring-bundle` fails with bare "TypeError: fetch failed" — endpoint fallback targets internal-only hosts (test.api/dev.api.salesforce.com)

CLI Version:
@salesforce/cli/2.149.9

Architecture:
win32-arm64

Node Version:
node-v24.14.1

Plugin Version:
@oclif/plugin-autocomplete 3.2.56 (core)
@oclif/plugin-commands 4.1.63 (core)
@oclif/plugin-help 6.2.58 (core)
@oclif/plugin-not-found 3.2.93 (core)
@oclif/plugin-plugins 5.4.87 (core)
@oclif/plugin-search 1.2.54 (core)
@oclif/plugin-update 4.7.59 (core)
@oclif/plugin-version 2.2.57 (core)
@oclif/plugin-warn-if-update-available 3.1.73 (core)
@oclif/plugin-which 3.2.61 (core)
@salesforce/cli 2.149.9 (core)
agent 2.0.5 (user)
apex 4.1.0 (core)
api 2.0.9 (core)
auth 5.0.6 (core)
code-analyzer 5.12.0 (user)
data 5.1.5 (core)
deploy-retrieve 4.1.2 (core)
info 4.0.9 (core)
limits 4.0.3 (core)
marketplace 2.0.5 (core)
org 6.0.9 (core)
packaging 3.0.5 (core)
schema 4.0.5 (core)
settings 3.0.5 (core)
sobject 2.0.5 (core)
telemetry 4.0.5 (core)
templates 57.0.9 (core)
trust 4.0.9 (core)
user 5.0.1 (core)

OS and Version:
Windows_NT 10.0.26200

Shell:
powershell

---

**Title:** `agent publish authoring-bundle` fails with bare "TypeError: fetch
failed" — endpoint fallback targets internal-only hosts
(test.api/dev.api.salesforce.com)

## Summary

`sf agent publish authoring-bundle` fails with an unactionable
`TypeError: fetch failed` (`UND_ERR_CONNECT_TIMEOUT`). Root cause is a
combination of three behaviors in `@salesforce/agents`
(`lib/utils.js` → `requestWithEndpointFallback`, used by
`lib/agents/scriptAgentPublisher.js`):

1. `POST https://api.salesforce.com/einstein/ai-agent/v1.1/authoring/agents`
returns **404 with an empty body** for my org (an Agentforce Developer
Edition on an `orgfarm-*.develop.my.salesforce.com` instance). Notably,
the **same org succeeds** against
`POST https://api.salesforce.com/einstein/ai-agent/v1.1/authoring/scripts`
(`sf agent validate authoring-bundle` passes) — so prod SFAP serves the
`/scripts` route but 404s the `/agents` route for this org, which looks
like a routing/provisioning inconsistency rather than a wholly
unprovisioned org.
2. On the 404, the library falls back to `test.api.salesforce.com`. That
hostname publicly resolves to an **internal-only ingress**:
`test.api.salesforce.com` → CNAME
`ingress-internal.core4.test1-uswest2.aws.sfdc.cl` →
34.210.29.116 / 44.228.60.86 / 34.213.108.10, none of which accept
connections from the public internet (connect timeout, verified with
curl). `dev.api.salesforce.com` is the same:
`ingress-internal.core002.dev1-uswest2.aws.sfdc.cl`.
3. The fallback loop throws immediately on any **non-404** error, so the
connect timeout on `test.` aborts the chain before `dev.` is attempted —
and the user receives a raw undici `fetch failed` with no indication of
which endpoint failed or why.

Net effect: for any org whose `/authoring/agents` route isn't served by prod
SFAP, an external user gets a dead-end fallback chain that cannot succeed
from outside Salesforce's network, surfaced as a generic fetch error.

## Steps to reproduce

From a fresh Agentforce Developer Edition (signup via the Agentforce DE form;
Einstein + Agentforce enabled in Setup), in an SFDX project:

```
sf agent generate agent-spec -o --type customer --role "..." --company-name "..." --company-description "..." --max-topics 3 --output-file specs/agentSpec.yaml
sf agent generate authoring-bundle -o -f specs/agentSpec.yaml -n "Test Agent" --api-name Test_Agent
sf agent validate authoring-bundle --api-name Test_Agent -o # succeeds
sf agent publish authoring-bundle --api-name Test_Agent -o # fails
```

## Actual result

```
TypeError: fetch failed
[cause]: ConnectTimeoutError: Connect Timeout Error
(attempted addresses: 34.210.29.116:443, 44.228.60.86:443, 34.213.108.10:443, timeout: 10000ms)
code: 'UND_ERR_CONNECT_TIMEOUT'
```

Trace-level logs show the sequence: POST to
`api.salesforce.com/einstein/ai-agent/v1.1/authoring/agents` (404), then POST
to `test.api.salesforce.com/...` (connect timeout, command dies).

## Expected result

Any of:
- prod `api.salesforce.com` serves `/authoring/agents` for orgs it already
serves `/authoring/scripts` for; or
- the fallback treats a connect timeout as fall-through rather than fatal,
and reports which endpoints were attempted; or
- a clear error such as "the agent authoring API is not available for this
org type" instead of a raw fetch failure.

## Diagnostics already ruled out

- Not local DNS/network in general: `api.salesforce.com` resolves correctly
(155.226.144.x) and connects fine via both curl and Node's resolver; the
org's My Domain connects fine; `validate authoring-bundle` succeeds.
- Not fixed by upgrading: reproduced on `@salesforce/plugin-agent` 2.0.3
(CLI-bundled) and 2.0.5 (user-installed).
- The 404 reproduces outside the CLI: `curl -X POST` to the `/authoring/agents`
URL with a valid org access token returns 404 with `content-length: 0`.

## Environment

- sf CLI:
- `@salesforce/plugin-agent`: 2.0.3 and 2.0.5 (both reproduce)
- OS: Windows 11 Pro (10.0.26200)
- Org: Agentforce Developer Edition, `orgfarm-*.develop.my.salesforce.com`
instance, Einstein and Agentforce enabled in Setup

## Workaround

The non-Agent-Script path works against the same org: `sf agent create
--spec specs/agentSpec.yaml ...` creates the agent via the org's own API and
retrieves its metadata normally. Only the Agent Script
publish flow is affected.

Start with requestWithEndpointFallback in lib/utils.js and its use from lib/agents/scriptAgentPublisher.js, then reproduce the publish authoring-bundle flow against the documented endpoints. Compare the 404, timeout, and error-reporting paths; done means the fallback behavior or resulting error clearly reflects the endpoints attempted and the org's API availability.

Written by the indexing model from the issue text.