feat: add helpful error messages for agent not found cases

Wrap BotDefinition and BotVersion queries in try-catch blocks to provide
user-friendly error messages when an agent or version doesn't exist,
instead of showing raw SOQL error.

Author: WillieRuemmele

src/commands/org/open/agent.ts

@@ -15,7 +15,7 @@
  */
 
 import { Flags } from '@salesforce/sf-plugins-core';
-import { Connection, Messages } from '@salesforce/core';
+import { Connection, Messages, SfError } from '@salesforce/core';
 import { OrgOpenCommandBase } from '../../../shared/orgOpenCommandBase.js';
 import { type OrgOpenOutput } from '../../../shared/orgTypes.js';
 
@@ -90,12 +90,25 @@ export class OrgOpenAgent extends OrgOpenCommandBase<OrgOpenOutput> {
 // Build the URL part to the Agent Builder given a Bot API name.
 const buildRetUrl = async (conn: Connection, botName: string, version?: string): Promise<string> => {
   const query = `SELECT id FROM BotDefinition WHERE DeveloperName='${botName}'`;
-  const botId = (await conn.singleRecordQuery<{ Id: string }>(query)).Id;
+  let botId: string;
+  try {
+    botId = (await conn.singleRecordQuery<{ Id: string }>(query)).Id;
+  } catch (error) {
+    throw new SfError(`No agent found with API name '${botName}' in the target org.`, 'AgentNotFound');
+  }
+
   const queryParams = new URLSearchParams({ copilotId: botId });
   if (version) {
     const versionQuery = `SELECT Id FROM BotVersion WHERE BotDefinitionId='${botId}' AND VersionNumber=${version}`;
-    const versionId = (await conn.singleRecordQuery<{ Id: string }>(versionQuery)).Id;
-    queryParams.set('versionId', versionId);
+    try {
+      const versionId = (await conn.singleRecordQuery<{ Id: string }>(versionQuery)).Id;
+      queryParams.set('versionId', versionId);
+    } catch (error) {
+      throw new SfError(
+        `No version '${version}' found for agent '${botName}' in the target org.`,
+        'AgentVersionNotFound'
+      );
+    }
   }
   return `AiCopilot/copilotStudio.app#/copilot/builder?${queryParams.toString()}`;
 };

test/unit/org/open/agent.test.ts

@@ -337,6 +337,60 @@ describe('org:open:agent', () => {
     });
   });
 
+  describe('error handling', () => {
+    it('throws helpful error when agent API name does not exist', async () => {
+      const nonExistentAgent = 'NonExistent_Agent';
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      spies.get('singleRecordQuery').rejects(new Error('No records found'));
+
+      try {
+        await OrgOpenAgent.run([
+          '--json',
+          '--target-org',
+          testOrg.username,
+          '--url-only',
+          '--api-name',
+          nonExistentAgent,
+        ]);
+        assert.fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).to.exist;
+        expect((error as Error).message).to.include(`No agent found with API name '${nonExistentAgent}'`);
+        expect((error as Error).name).to.equal('AgentNotFound');
+      }
+    });
+
+    it('throws helpful error when agent version does not exist', async () => {
+      const nonExistentVersion = '999';
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const singleRecordQueryStub = spies.get('singleRecordQuery');
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      singleRecordQueryStub.onFirstCall().resolves({ Id: mockBotId }); // BotDefinition succeeds
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
+      singleRecordQueryStub.onSecondCall().rejects(new Error('No records found')); // BotVersion fails
+
+      try {
+        await OrgOpenAgent.run([
+          '--json',
+          '--target-org',
+          testOrg.username,
+          '--url-only',
+          '--api-name',
+          mockBotName,
+          '--version',
+          nonExistentVersion,
+        ]);
+        assert.fail('Should have thrown an error');
+      } catch (error) {
+        expect(error).to.exist;
+        expect((error as Error).message).to.include(
+          `No version '${nonExistentVersion}' found for agent '${mockBotName}'`
+        );
+        expect((error as Error).name).to.equal('AgentVersionNotFound');
+      }
+    });
+  });
+
   describe('api-version flag', () => {
     it('respects api-version flag with api-name', async () => {
       const apiVersion = '59.0';