chore: merge with nga, resolve conflicts

Author: WillieRuemmele

README.md

@@ -1,47 +1,51 @@
 # summary
 
-Generate an authoring bundle from an agent specification.
+Generate a local authoring bundle from an existing agent spec YAML file.
 
 # description
 
-Generates an authoring bundle containing Agent and its meta.xml file from an agent specification file.
+Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent. Use this command to generate an authoring bundle based on an agent spec YAML file, which you create with the "agent create agent-spec" command.
+
+By default, authoring bundles are generated in the force-app/main/default/aiAuthoringBundles/<api-name> directory. Use the --output-dir to generate them elsewhere.
 
 # flags.spec.summary
 
-Path to the agent specification file.
+Path to the agent spec YAML file.
 
 # flags.output-dir.summary
 
-Directory where the authoring bundle files will be generated.
+Directory where the authoring bundle files are generated.
 
 # flags.name.summary
 
 Name (label) of the authoring bundle.
 
 # flags.api-name.summary
 
-API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name must not exist in the org.
+API name of the new authoring bundle; if not specified, the API name is derived from the authoring bundle name (label); the API name can't exist in the org.
 
 # flags.api-name.prompt
 
 API name of the new authoring bundle
 
 # examples
 
-- Generate an authoring bundle from a specification file:
-  <%= config.bin %> <%= command.id %> --spec-file path/to/spec.yaml --name "My Authoring Bundle"
+- Generate an authoring bundle from the "specs/agentSpec.yaml" agent spec YAML file and give it the label "My Authoring Bundle":
+
+  <%= config.bin %> <%= command.id %> --spec-file specs/agentSpec.yaml --name "My Authoring Bundle"
+
+- Same as previous example, but generate the files in the other-package-dir/main/default/aiAuthoringBundles directory:
 
-- Generate an authoring bundle with a custom output directory:
-  <%= config.bin %> <%= command.id %> --spec-file path/to/spec.yaml --name "My Authoring Bundle" --output-dir path/to/output
+  <%= config.bin %> <%= command.id %> --spec-file specs/agentSpec.yaml --name "My Authoring Bundle" --output-dir other-package-dir/main/default/aiAuthoringBundles
 
 # error.no-spec-file
 
-No agent specification file found at the specified path.
+No agent spec YAML file found at the specified path.
 
 # error.invalid-spec-file
 
-The specified file is not a valid agent specification file.
+The specified file is not a valid agent spec YAML file.
 
 # error.failed-to-create-agent
 
-Failed to create Agent from the agent specification.
+Failed to create a next-gen agent from the agent spec YAML file.

messages/agent.generate.authoring-bundle.md

@@ -12,19 +12,19 @@ When the session concludes, the command asks if you want to save the API respons
 
 Find the agent's API name in its Agent Details page of your org's Agentforce Studio UI in Setup. If your agent is currently deactivated, use the "agent activate" CLI command to activate it.
 
-IMPORTANT: Before you use this command, you must complete a number of configuration steps in your org and your DX project. The examples in this help assume you've completed the steps. See "Preview an Agent" in the "Agentforce Developer Guide" for complete documentation: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview.html.
+IMPORTANT: Before you use this command, you must complete a number of configuration steps in your org and your DX project. For example, you must first create the link to a client connected app using the "org login web --client-app" CLI command to then get the value of the --client-app flag of this command. The examples in this help assume you've completed the steps. See "Preview an Agent" in the "Agentforce Developer Guide" for complete documentation: https://developer.salesforce.com/docs/einstein/genai/guide/agent-dx-preview.html.
 
 # flags.api-name.summary
 
 API name of the agent you want to interact with.
 
 # flags.authoring-bundle.summary
 
-Preview an ephemeral agent by specifying the API name of the Authoring Bundle metadata
+Preview a next-gen agent by specifying the API name of the authoring bundle metadata component that implements it. 
 
 # flags.client-app.summary
 
-Name of the linked client app to use for the agent connection. You must have previously created this link with "org login web --client-app". Run "org display" to see the available linked client apps.
+Name of the linked client app to use for the agent connection.
 
 # flags.output-dir.summary
 

messages/agent.preview.md

@@ -1,35 +1,40 @@
 # summary
 
-Publish an Agent Authoring Bundle as a new agent
+Publish an authoring bundle to your org, which results in a new next-gen agent.
 
 # description
 
-Publishes an Agent Authoring Bundle by compiling the .agent file and creating a new agent in your org.
+When you publish an authoring bundle to your org, a number of things happen. First, this command validates that the agent file (with extension ".agent") successfully compiles. Then the authoring bundle metadata component is deployed to the org, and all associated metadata components, such as the Bot, BotVersion, and GenAiXXX components, are either created or updated. The org then creates a new next-gen agent based on the deployed authoring bundle and associated metadata. Finally, all the metadata associated with the new agent is retrieved back to your local DX project.
+
+Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent.
+
+This command requires the API name of the authoring bundle; if you don't provide it with the --api-name flag, the command prompts you for it.
 
 # examples
 
-- Publish an Agent Authoring Bundle:
-  <%= config.bin %> <%= command.id %> --api-name path/to/bundle --agent-name "My New Agent" --target-org myorg@example.com
+- Publish an authoring bundle with API name MyAuthoringBundle to the org with alias "my-org", resulting in a new agent named "My Fab Agent"::
+
+  <%= config.bin %> <%= command.id %> --api-name MyAuthoringbundle --agent-name "My Fab Agent" --target-org my-org
 
 # flags.api-name.summary
 
-API name of the Agent Authoring Bundle to publish.
+API name of the authoring bundle you want to publish.
 
 # flags.api-name.prompt
 
 API name of the authoring bundle to publish
 
 # flags.agent-name.summary
 
-Name for the new agent to be created
+Name for the new agent that is created from the published authoring bundle.
 
 # error.missingRequiredFlags
 
-Required flag(s) missing: %s
+Required flag(s) missing: %s.
 
 # error.invalidBundlePath
 
-Invalid bundle path. Please provide a valid path to an Agent Authoring Bundle.
+Invalid bundle path. Provide a valid directory path to an authoring bundle.
 
 # error.publishFailed
 
@@ -42,4 +47,4 @@ Could not find a .bundle-meta.xml file with API name '%s' in the project.
 
 # error.agentNotFoundAction
 
-Please check that the API name is correct and that the .agent file exists in your project directory.
+Check that the API name is correct and that the .agent file exists in your project directory.

messages/agent.publish.authoring-bundle.md

@@ -1,35 +1,40 @@
 # summary
 
-Validate an Agent Authoring Bundle
+Validate a local authoring bundle to ensure it compiles successfully and can be used to create a next-gen agent.
 
 # description
 
-Validates an Agent Authoring Bundle by compiling the .agent file and checking for errors.
+Authoring bundles are metadata types that represent the next-gen Salesforce agents. Their exact metadata name is AiAuthoringBundle and they consist of a standard "\*-meta.xml" metadata file and an agent file (with extension ".agent") that fully describes the next-gen agent. Generate a local authoring bundle with the "agent generate authoring-bundle" command.
+
+This command validates that the agent file (with extension ".agent") that's part of the authoring bundle compiles without errors and can later be used to successfully create a next-gen agent.
+
+This command requires the API name of the authoring bundle; if you don't provide it with the --api-name flag, the command prompts you for it.
 
 # examples
 
-- Validate an Agent Authoring Bundle:
-  <%= config.bin %> <%= command.id %> --api-name path/to/bundle
+- Validate a local authoring bundle with API name MyAuthoringBundle:
+
+  <%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle
 
 # flags.api-name.summary
 
-API name of the Agent Authoring Bundle to validate.
+API name of the authoring bundle you want to validate.
 
 # flags.api-name.prompt
 
 API name of the authoring bundle to validate
 
 # error.missingRequiredFlags
 
-Required flag(s) missing: %s
+Required flag(s) missing: %s.
 
 # error.invalidBundlePath
 
-Invalid bundle path. Please provide a valid path to an Agent Authoring Bundle.
+Invalid authoring bundle path. Provide a valid directory path to the authoring bundle you want to validate.
 
 # error.compilationFailed
 
-Agent compilation failed with the following errors:
+Compilation of the agent file failed with the following errors:
 %s
 
 # error.agentNotFound
@@ -38,4 +43,4 @@ Could not find a .bundle-meta.xml file with API name '%s' in the project.
 
 # error.agentNotFoundAction
 
-Please check that the API name is correct and that the .agent file exists in your project directory.
+Check that the API name is correct and that the ".agent" file exists in your project directory.

messages/agent.validate.authoring-bundle.md

@@ -1,19 +1,19 @@
 {
   "name": "@salesforce/plugin-agent",
   "description": "Commands to interact with Salesforce agents",
-  "version": "1.24.14-demo.7",
+  "version": "1.24.14-demo.9",
   "author": "Salesforce",
   "bugs": "https://github.com/forcedotcom/cli/issues",
   "dependencies": {
     "@inquirer/core": "^10.2.2",
     "@inquirer/prompts": "^7.8.6",
     "@oclif/core": "^4",
     "@oclif/multi-stage-output": "^0.8.23",
-    "@salesforce/agents": "^0.18.1",
+    "@salesforce/agents": "nga",
     "@salesforce/core": "^8.23.1",
     "@salesforce/kit": "^3.2.3",
     "@salesforce/sf-plugins-core": "^12.2.4",
-    "@salesforce/source-deploy-retrieve": "^12.22.1",
+    "@salesforce/source-deploy-retrieve": "^12.25.0",
     "@salesforce/types": "^1.4.0",
     "@types/glob": "^9.0.0",
     "ansis": "^3.3.2",

package.json

@@ -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.createAgentScript(conn, specContents);
+      const agent = await Agent.createAgentScript(conn, { ...specContents, ...{ name, developerName: bundleApiName } });
       // Create output directory if it doesn't exist
       mkdirSync(targetOutputDir, { recursive: true });
       writeFileSync(agentPath, agent);

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

@@ -168,7 +168,7 @@ export default class AgentPreview extends SfCommand<AgentPreviewResult> {
 
     const outputDir = await resolveOutputDir(flags['output-dir'], flags['apex-debug']);
     // Both classes share the same interface for the methods we need
-    const agentPreview: Preview | AgentSimulate =
+    const agentPreview =
       selectedAgent.source === AgentSource.ORG
         ? new Preview(jwtConn, selectedAgent.Id)
         : new AgentSimulate(jwtConn, selectedAgent.path, true);

src/commands/agent/preview.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.compileAgentScript(
+      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.compiledArtifact!);
+      const result = await Agent.publishAgentJson(conn, this.project!, compileResponse.compiledArtifact);
       mso.stop();
 
       return {

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

@@ -20,6 +20,7 @@ import { Messages, SfError } from '@salesforce/core';
 import { MultiStageOutput } from '@oclif/multi-stage-output';
 import { Agent, findAuthoringBundle } from '@salesforce/agents';
 import { colorize } from '@oclif/core/ux';
+import { throwAgentCompilationError } from '../../../common.js';
 import { FlaggablePrompt, promptForAgentFiles } from '../../../flags.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
@@ -98,24 +99,35 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
       ],
     });
 
-    mso.skipTo('Validating Authoring Bundle');
-    const targetOrg = flags['target-org'];
-    const conn = targetOrg.getConnection(flags['api-version']);
-    const result = await Agent.compileAgentScript(
-      conn,
-      readFileSync(join(authoringBundleDir, `${apiName}.agent`), 'utf8')
-    );
-    mso.updateData({ status: 'COMPLETED' });
-    mso.stop('completed');
-    if (result.status === 'failure') {
+    try {
+      mso.skipTo('Validating Authoring Bundle');
+      const targetOrg = flags['target-org'];
+      const conn = targetOrg.getConnection(flags['api-version']);
+      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);
       let count = 0;
-      const formattedError = result.errors
-        .map((e) => {
+      const rawError = err.message ? err.message : err.name;
+      const formattedError = rawError
+        .split('\n')
+        .map((line) => {
           count += 1;
-          return `- ${colorize('red', e.errorType)} ${e.description}: ${e.lineStart}:${e.colStart} / ${e.lineEnd}:${
-            e.colEnd
-          }`;
+          const type = line.split(':')[0];
+          const rest = line.includes(':') ? line.substring(line.indexOf(':')).trim() : '';
+          return `- ${colorize('red', type)}${rest}`;
         })
         .join('\n');
 
@@ -125,11 +137,7 @@ export default class AgentValidateAuthoringBundle extends SfCommand<AgentValidat
       this.log(messages.getMessage('error.compilationFailed', [formattedError]));
       return {
         success: false,
-        errors: [formattedError],
-      };
-    } else {
-      return {
-        success: true,
+        errors: err.message.split('\n'),
       };
     }
   }