feat: handle agent compilation errors

Author: EstebanRomero84

src/commands/agent/generate/authoring-bundle.ts

@@ -134,7 +134,7 @@ export default class AgentGenerateAuthoringBundle extends SfCommand<AgentGenerat
       // Write Agent file
       const conn = targetOrg.getConnection(flags['api-version']);
       const specContents = YAML.parse(readFileSync(spec, 'utf8')) as AgentJobSpec;
-      const agent = await Agent.createAgent(conn, specContents);
+      const agent = await Agent.createAgentScript(conn, specContents);
       // Create output directory if it doesn't exist
       mkdirSync(targetOutputDir, { recursive: true });
       writeFileSync(agentPath, agent);

src/commands/agent/publish/authoring-bundle.ts

@@ -23,6 +23,7 @@ import { Agent, findAuthoringBundle } from '@salesforce/agents';
 import { RequestStatus, type ScopedPostRetrieve } from '@salesforce/source-deploy-retrieve';
 import { ensureArray } from '@salesforce/kit';
 import { FlaggablePrompt, promptForAgentFiles } from '../../../flags.js';
+import { throwAgentCompilationError } from '../../../common.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.publish.authoring-bundle');
@@ -103,12 +104,15 @@ export default class AgentPublishAuthoringBundle extends SfCommand<AgentPublishA
       const conn = targetOrg.getConnection(flags['api-version']);
 
       // First compile the .agent file to get the Agent JSON
-      const agentJson = await Agent.compileAgent(
+      const compileResponse = await Agent.compileAgentScript(
         conn,
         readFileSync(join(authoringBundleDir, `${apiName}.agent`), 'utf8')
       );
-      mso.skipTo('Publish Agent');
-
+      if (compileResponse.status === 'success') {
+        mso.skipTo('Publish Agent');
+      } else {
+        throwAgentCompilationError(compileResponse.errors);
+      }
       // Then publish the Agent JSON to create the agent
       // Set up lifecycle listeners for retrieve events
       Lifecycle.getInstance().on('scopedPreRetrieve', () => {
@@ -129,7 +133,7 @@ export default class AgentPublishAuthoringBundle extends SfCommand<AgentPublishA
         }
         return Promise.resolve();
       });
-      const result = await Agent.publishAgentJson(conn, this.project!, agentJson);
+      const result = await Agent.publishAgentJson(conn, this.project!, compileResponse.compiledArtifact);
       mso.stop();
 
       return {

src/commands/agent/validate/authoring-bundle.ts

@@ -21,6 +21,7 @@ import { MultiStageOutput } from '@oclif/multi-stage-output';
 import { Agent, findAuthoringBundle } from '@salesforce/agents';
 import { Duration, sleep } from '@salesforce/kit';
 import { colorize } from '@oclif/core/ux';
+import { throwAgentCompilationError } from '../../../common.js';
 import { FlaggablePrompt, promptForAgentFiles } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
@@ -105,12 +106,19 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
       const conn = targetOrg.getConnection(flags['api-version']);
       // Call Agent.compileAgent() API
       await sleep(Duration.seconds(2));
-      await Agent.compileAgent(conn, readFileSync(join(authoringBundleDir, `${apiName}.agent`), 'utf8'));
-      mso.updateData({ status: 'COMPLETED' });
-      mso.stop('completed');
-      return {
-        success: true,
-      };
+      const result = await Agent.compileAgentScript(
+        conn,
+        readFileSync(join(authoringBundleDir, `${apiName}.agent`), 'utf8')
+      );
+      if (result.status === 'success') {
+        mso.updateData({ status: 'COMPLETED' });
+        mso.stop('completed');
+        return {
+          success: true,
+        };
+      } else {
+        throwAgentCompilationError(result.errors);
+      }
     } catch (error) {
       // Handle validation errors
       const err = SfError.wrap(error);
@@ -121,7 +129,7 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
           count += 1;
           const type = line.split(':')[0];
           const rest = line.substring(line.indexOf(':')).trim();
-          return `- ${colorize('red', type)} ${rest}`;
+          return `- ${colorize('red', type)}${rest}`;
         })
         .join('\n');
 

src/common.ts

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2025, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { EOL } from 'node:os';
+import { SfError } from '@salesforce/core';
+import { CompilationError } from '@salesforce/agents';
+
+/**
+ * Utility function to generate SfError when there are agent compilation errors.
+ *
+ * @param compilationErrors - The compilation errors as strings, CompilationError objects, or array of either
+ * @throws SfError - Always throws a Salesforce CLI error
+ */
+export function throwAgentCompilationError(compilationErrors: CompilationError[]): never {
+  const errors = compilationErrors;
+
+  throw SfError.create({
+    name: 'CompileAgentScriptError',
+    message: errors.map((e) => `${e.errorType}: ${e.description} [Ln ${e.lineStart}, Col ${e.colStart}]`).join(EOL),
+    data: errors,
+  });
+}