@salesforce/plugin-agent 1.32.10 → 1.32.12

package/README.md

@@ -126,7 +126,7 @@ EXAMPLES
     $ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
 ```
 
-_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/activate.ts)_
 
 ## `sf agent create`
 
@@ -193,7 +193,7 @@ EXAMPLES
     $ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
 ```
 
-_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/create.ts)_
 
 ## `sf agent deactivate`
 
@@ -234,7 +234,7 @@ EXAMPLES
     $ sf agent deactivate --api-name Resort_Manager --target-org my-org
 ```
 
-_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/deactivate.ts)_
 
 ## `sf agent generate agent-spec`
 
@@ -341,7 +341,7 @@ EXAMPLES
     $ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
 ```
 
-_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/generate/agent-spec.ts)_
+_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/generate/agent-spec.ts)_
 
 ## `sf agent generate authoring-bundle`
 
@@ -418,18 +418,22 @@ EXAMPLES
       other-package-dir/main/default --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/generate/authoring-bundle.ts)_
+_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/generate/authoring-bundle.ts)_
 
 ## `sf agent generate template`
 
-Generate an agent template from an existing agent in your DX project so you can then package the template in a managed package.
+Generate an agent template from an existing agent in your DX project so you can then package the template in a second-generation managed package.
 
 ```
 USAGE
-  $ sf agent generate template --agent-version <value> -f <value> [--json] [--flags-dir <value>] [--api-version <value>]
+  $ sf agent generate template -s <value> --agent-version <value> -f <value> [--json] [--flags-dir <value>] [--api-version
+    <value>] [-r <value>]
 
 FLAGS
   -f, --agent-file=<value>     (required) Path to an agent (Bot) metadata file.
+  -r, --output-dir=<value>     Directory where the generated BotTemplate and GenAiPlannerBundle files are saved.
+  -s, --source-org=<value>     (required) Username or alias of the namespaced scratch org that contains the agent which
+                               this template is based on.
       --agent-version=<value>  (required) Version of the agent (BotVersion).
       --api-version=<value>    Override the api version used for api requests made by this command
 
@@ -438,35 +442,45 @@ GLOBAL FLAGS
   --json               Format output as json.
 
 DESCRIPTION
-  Generate an agent template from an existing agent in your DX project so you can then package the template in a managed
-  package.
+  Generate an agent template from an existing agent in your DX project so you can then package the template in a
+  second-generation managed package.
+
+  WARNING: This command doesn't work for agents that were created from an Agent Script file. In other words, you can't
+  currently package an agent template for agents that use Agent Script.
 
   At a high-level, agents are defined by the Bot, BotVersion, and GenAiPlannerBundle metadata types. The
   GenAiPlannerBundle type in turn defines the agent's topics and actions. This command uses the metadata files for these
-  three types, located in your local DX project, to generate a BotTemplate file for a specific agent (Bot). You then use
-  the BotTemplate file, along with the GenAiPlannerBundle file that references the BotTemplate, to package the template
-  in a managed package that you can share between orgs or on AppExchange.
+  three types, located in your local DX project, to generate a BotTemplate metadata file for a specific agent (Bot). You
+  then use the BotTemplate metadata file, along with the GenAiPlannerBundle metadata file that references the
+  BotTemplate, to package the template in a managed package that you can share between orgs or on AppExchange.
 
   Use the --agent-file flag to specify the relative or full pathname of the Bot metadata file, such as
   force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml. A single Bot can have multiple
-  BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion file must exist
-  locally. For example, if you specify "--agent-version 4", then the file
+  BotVersions, so use the --agent-version flag to specify the version. The corresponding BotVersion metadata file must
+  exist locally. For example, if you specify "--agent-version 4", then the file
   force-app/main/default/bots/My_Awesome_Agent/v4.botVersion-meta.xml must exist.
 
-  The new BotTemplate file is generated in the "botTemplates" directory in your local package directory, and has the
-  name <Agent_API_name>_v<Version>_Template.botTemplate-meta.xml, such as
-  force-app/main/default/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full
-  pathname of the generated files when it completes.
+  The new BotTemplate metadata file is generated in the "botTemplates" directory in the output directory specified with
+  the --output-dir flag, and has the name <Agent_API_name>\_v<Version>\_Template.botTemplate-meta.xml, such as
+  my-package/botTemplates/My_Awesome_Agent_v4_Template.botTemplate-meta.xml. The command displays the full pathname of
+  the generated files when it completes.
+
+  See "Develop and Package Agent Templates Using Scratch Orgs"
+  (https://developer.salesforce.com/docs/atlas.en-us.pkg2_dev.meta/pkg2_dev/dev2gp_package_agent_templates.htm) for
+  details about the complete process, which includes using a scratch org to create and test the agent, retrieving the
+  agent metadata to your DX project, running this command to create the agent template, and then packaging the template.
 
 EXAMPLES
-  Generate an agent template from a Bot metadata file in your DX project that corresponds to the My_Awesome_Agent
-  agent; use version 1 of the agent.
+  Generate an agent template from the My_Awesome_Agent Bot metadata file in your DX project and save the BotTemplate
+  and GenAiPlannerBundle to the specified directory; use version 1 of the agent. The agent that the template is based
+  on is in the org with alias "my-scratch-org":
 
     $ sf agent generate template --agent-file \
-      force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1
+      force-app/main/default/bots/My_Awesome_Agent/My_Awesome_Agent.bot-meta.xml --agent-version 1 --output-dir \
+      my-package --source-org my-scratch-org
 ```
 
-_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/generate/template.ts)_
 
 ## `sf agent generate test-spec`
 
@@ -531,7 +545,7 @@ EXAMPLES
       force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
 ```
 
-_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/generate/test-spec.ts)_
+_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/generate/test-spec.ts)_
 
 ## `sf agent preview`
 
@@ -604,7 +618,7 @@ EXAMPLES
     $ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
 ```
 
-_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -659,7 +673,7 @@ EXAMPLES
     $ sf agent preview end --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -717,7 +731,7 @@ EXAMPLES
     $ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/preview/send.ts)_
 
 ## `sf agent preview sessions`
 
@@ -750,7 +764,7 @@ EXAMPLES
     $ sf agent preview sessions
 ```
 
-_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -807,7 +821,7 @@ EXAMPLES
     $ sf agent preview start --api-name My_Published_Agent
 ```
 
-_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -856,7 +870,7 @@ EXAMPLES
     $ sf agent publish authoring-bundle --api-name MyAuthoringbundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/publish/authoring-bundle.ts)_
+_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -911,7 +925,7 @@ EXAMPLES
     $ sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview
 ```
 
-_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -946,7 +960,7 @@ EXAMPLES
     $ sf agent test list --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -1012,7 +1026,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1085,7 +1099,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1159,7 +1173,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/test/run.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1206,6 +1220,6 @@ EXAMPLES
     $ sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.10/src/commands/agent/validate/authoring-bundle.ts)_
+_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.12/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

package/lib/commands/agent/generate/template.d.ts

@@ -1,8 +1,15 @@
 import { SfCommand } from '@salesforce/sf-plugins-core';
-import type { BotTemplate, GenAiPlanner, BotDialogGroup, ConversationDefinitionGoal, ConversationVariable } from '@salesforce/types/metadata';
+import type { Connection } from '@salesforce/core';
+import type { BotTemplate, BotDialogGroup, GenAiPlannerBundle, ConversationDefinitionGoal, ConversationVariable, GenAiFunction, GenAiPlugin, GenAiPlannerFunctionDef } from '@salesforce/types/metadata';
+/** Global function names that are allowed to be emitted in genAiFunctions when converting localActionLinks. */
+export declare const ALLOWED_GLOBAL_FUNCTIONS: Set<string>;
 export type GenAiPlannerBundleExt = {
-    GenAiPlannerBundle: GenAiPlanner & {
+    GenAiPlannerBundle: GenAiPlannerBundle & {
         botTemplate?: string;
+        localActionLinks?: GenAiPlannerFunctionDef[];
+        localTopicLinks: GenAiPlannerFunctionDef[];
+        localTopics?: GenAiPlugin[];
+        plannerActions?: GenAiFunction[];
     };
 };
 export type BotTemplateExt = {
@@ -28,8 +35,44 @@ export default class AgentGenerateTemplate extends SfCommand<AgentGenerateTempla
     static readonly requiresProject = true;
     static readonly flags: {
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'source-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
         'agent-version': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
         'agent-file': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'output-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<AgentGenerateTemplateResult>;
 }
+/**
+ * Extracts local topics and actions from the GenAiPlannerBundle and validates that each has a `source` reference to its global counterpart.
+ * Throws if any local topic or action is missing `source`.
+ *
+ * @param genAiPlannerBundleMetaJson - The GenAiPlannerBundle metadata to read from
+ * @returns { localTopics, localActions } - The local topics and the flattened local actions from all plugins
+ */
+export declare const getLocalAssets: (genAiPlannerBundleMetaJson: GenAiPlannerBundleExt) => {
+    localTopics: GenAiPlugin[];
+    localActions: GenAiFunction[];
+};
+/**
+ * Uses localTopics' <source> elements to identify global assets, then updates topic links (genAiPlugins), action links (genAiFunctions), attributeMappings and ruleExpressionAssignments.
+ * Replaces localTopicLinks with genAiPlugins. Replaces localActionLinks with genAiFunctions.
+ */
+export declare const replaceReferencesToGlobalAssets: (genAiPlannerBundleMetaJson: GenAiPlannerBundleExt, localTopics: GenAiPlugin[]) => void;
+/** Tooling API row for GenAiPluginDefinition or GenAiFunctionDefinition (shared field shape). */
+export type GenAiBundledAssetToolingRecord = {
+    Id: string;
+    DeveloperName: string;
+    NamespacePrefix: string | null;
+    IsLocal: boolean;
+    Source: string | null;
+};
+/**
+ * Validates that local topics and actions reference global assets that exist in the source org.
+ *
+ * @param localTopics - Local genAiPlugin topics (GenAiPluginDefinition)
+ * @param localActions - Local genAiFunction actions (GenAiFunctionDefinition)
+ * @param connection - Source org connection (--source-org)
+ * @param namespaceFromSfdxProject - `namespace` from sfdx-project.json (empty if unset)
+ * @param warn - Command warn hook (e.g. `(msg) => this.warn(msg)`)
+ */
+export declare const validateGlobalAssets: (localTopics: GenAiPlugin[], localActions: GenAiFunction[], connection: Connection, namespaceFromSfdxProject: string, warn: (msg: string) => void) => Promise<void>;

package/lib/commands/agent/generate/template.js

@@ -14,10 +14,13 @@
  * limitations under the License.
  */
 import { join, dirname, basename, resolve } from 'node:path';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
-import { Messages, SfError } from '@salesforce/core';
+import { Messages, SfError, validateSalesforceId } from '@salesforce/core';
+import { ensureArray } from '@salesforce/kit';
 import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+/** Global function names that are allowed to be emitted in genAiFunctions when converting localActionLinks. */
+export const ALLOWED_GLOBAL_FUNCTIONS = new Set(['EmployeeCopilot__AnswerQuestionsWithKnowledge']);
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.generate.template');
 export default class AgentGenerateTemplate extends SfCommand {
@@ -27,6 +30,10 @@ export default class AgentGenerateTemplate extends SfCommand {
     static requiresProject = true;
     static flags = {
         'api-version': Flags.orgApiVersion(),
+        'source-org': Flags.requiredOrg({
+            summary: messages.getMessage('flags.source-org.summary'),
+            char: 's',
+        }),
         'agent-version': Flags.integer({
             summary: messages.getMessage('flags.agent-version.summary'),
             required: true,
@@ -37,10 +44,14 @@ export default class AgentGenerateTemplate extends SfCommand {
             required: true,
             exists: true,
         }),
+        'output-dir': Flags.directory({
+            summary: messages.getMessage('flags.output-dir.summary'),
+            char: 'r',
+        }),
     };
     async run() {
         const { flags } = await this.parse(AgentGenerateTemplate);
-        const { 'agent-file': agentFile, 'agent-version': botVersion } = flags;
+        const { 'agent-file': agentFile, 'agent-version': botVersion, 'output-dir': outputDir } = flags;
         if (!agentFile.endsWith('.bot-meta.xml')) {
             throw new SfError(messages.getMessage('error.invalid-agent-file'));
         }
@@ -50,24 +61,41 @@ export default class AgentGenerateTemplate extends SfCommand {
         // Since we are cloning the GenAiPlannerBundle, we need to use a different name than the Agent (Bot) we started with
         // We will use this name for the BotTemplate also to make it clear they are related
         const finalFilename = `${botName}_v${botVersion}_Template`;
-        // Build the base dir from the AgentFile
+        // Base path for reading metadata
         const basePath = resolve(dirname(agentFile), '..', '..');
         const botDir = join(basePath, 'bots', botName);
         const genAiPlannerBundleDir = join(basePath, 'genAiPlannerBundles');
-        const botTemplateDir = join(basePath, 'botTemplates');
+        const outputBase = resolve(outputDir ?? basePath);
+        const botTemplateDir = join(outputBase, 'botTemplates');
+        const outputGenAiPlannerBundleDir = join(outputBase, 'genAiPlannerBundles');
         const botTemplateFilePath = join(botTemplateDir, `${finalFilename}.botTemplate-meta.xml`);
-        const clonedGenAiPlannerBundleFilePath = join(genAiPlannerBundleDir, finalFilename, `${finalFilename}.genAiPlannerBundle`);
+        const clonedGenAiPlannerBundleFilePath = join(outputGenAiPlannerBundleDir, finalFilename, `${finalFilename}.genAiPlannerBundle`);
         // Parse the metadata files as JSON
         const botJson = xmlToJson(join(botDir, `${botName}.bot-meta.xml`), parser);
+        if (botJson.Bot.agentDSLEnabled) {
+            throw new SfError(messages.getMessage('error.nga-agent-not-supported'));
+        }
         const botVersionJson = xmlToJson(join(botDir, `v${botVersion}.botVersion-meta.xml`), parser);
         const genAiPlannerBundleMetaJson = xmlToJson(join(genAiPlannerBundleDir, botName, `${botName}.genAiPlannerBundle`), parser);
         // Modify the metadata files for final output
-        // TODO: Confirm this name (might be conversationDefinitionPlanners)
         genAiPlannerBundleMetaJson.GenAiPlannerBundle.botTemplate = finalFilename;
+        // Process local assets
+        const { localTopics, localActions } = getLocalAssets(genAiPlannerBundleMetaJson);
+        const connection = flags['source-org'].getConnection(flags['api-version']);
+        const resolvedProjectConfig = await this.project.resolveProjectConfig();
+        const namespaceFromSfdxProject = typeof resolvedProjectConfig.namespace === 'string' ? resolvedProjectConfig.namespace : '';
+        await validateGlobalAssets(localTopics, localActions, connection, namespaceFromSfdxProject, (msg) => this.warn(msg));
+        replaceReferencesToGlobalAssets(genAiPlannerBundleMetaJson, localTopics);
         const botTemplate = convertBotToBotTemplate(botJson, botVersionJson, finalFilename, botTemplateFilePath);
         // Build and save the metadata files
         jsonToXml(clonedGenAiPlannerBundleFilePath, genAiPlannerBundleMetaJson, builder);
         jsonToXml(botTemplateFilePath, botTemplate, builder);
+        if (outputDir) {
+            const copiedDirs = copyMetadataDirsIfPresent(basePath, outputBase);
+            if (copiedDirs.length > 0) {
+                this.warn(messages.getMessage('warn.copied-asset-directories', [copiedDirs.join(', ')]));
+            }
+        }
         this.log(`\nSaved BotTemplate to:\n - ${botTemplateFilePath}`);
         this.log(`Saved GenAiPlannerBundle to:\n - ${clonedGenAiPlannerBundleFilePath}`);
         return {
@@ -134,7 +162,228 @@ const jsonToXml = (filename, json, builder) => {
         writeFileSync(filename, xml);
     }
     catch (error) {
-        throw new SfError(`Failed save to file: ${filename}`);
+        throw new SfError(`Failed save to file: ${filename}`, undefined, undefined, undefined, error);
+    }
+};
+/**
+ * Extracts local topics and actions from the GenAiPlannerBundle and validates that each has a `source` reference to its global counterpart.
+ * Throws if any local topic or action is missing `source`.
+ *
+ * @param genAiPlannerBundleMetaJson - The GenAiPlannerBundle metadata to read from
+ * @returns { localTopics, localActions } - The local topics and the flattened local actions from all plugins
+ */
+export const getLocalAssets = (genAiPlannerBundleMetaJson) => {
+    const rawLocalTopics = genAiPlannerBundleMetaJson.GenAiPlannerBundle.localTopics;
+    const localTopics = Array.isArray(rawLocalTopics) ? rawLocalTopics : rawLocalTopics ? [rawLocalTopics] : [];
+    const localTopicsWithoutSource = localTopics.filter((topic) => !topic.source);
+    if (localTopicsWithoutSource.length > 0) {
+        throw new SfError(messages.getMessage('error.local-topics-without-source', [
+            localTopicsWithoutSource.map((topic) => topic.developerName).join(', '),
+        ]));
+    }
+    const actionsFromPlugins = localTopics.flatMap((plugin) => Array.isArray(plugin.localActions) ? plugin.localActions : plugin.localActions ? [plugin.localActions] : []);
+    const plannerBundle = genAiPlannerBundleMetaJson.GenAiPlannerBundle;
+    const plannerActions = Array.isArray(plannerBundle.plannerActions)
+        ? plannerBundle.plannerActions
+        : plannerBundle.plannerActions
+            ? [plannerBundle.plannerActions]
+            : [];
+    // localActions are the actions from the plugins and the plannerActions
+    const localActions = [...actionsFromPlugins, ...plannerActions];
+    if (localActions.length > 0) {
+        const localActionsWithoutSource = localActions.filter((action) => !action.source);
+        if (localActionsWithoutSource.length > 0) {
+            throw new SfError(messages.getMessage('error.local-actions-without-source', [
+                localActionsWithoutSource.map((action) => action.developerName ?? action.fullName).join(', '),
+            ]));
+        }
+    }
+    return { localTopics, localActions };
+};
+/**
+ * Uses localTopics' <source> elements to identify global assets, then updates topic links (genAiPlugins), action links (genAiFunctions), attributeMappings and ruleExpressionAssignments.
+ * Replaces localTopicLinks with genAiPlugins. Replaces localActionLinks with genAiFunctions.
+ */
+export const replaceReferencesToGlobalAssets = (genAiPlannerBundleMetaJson, localTopics) => {
+    const plannerBundle = genAiPlannerBundleMetaJson.GenAiPlannerBundle;
+    const localToGlobalAssets = buildLocalToGlobalAssetMap(localTopics, plannerBundle);
+    // replace localTopicLinks with global genAiPlugins
+    plannerBundle.genAiPlugins = localTopics.map((topic) => ({
+        genAiPluginName: topic.source,
+    }));
+    plannerBundle.localTopicLinks = [];
+    // Replaces localActionLinks with global genAiFunctions (only names in ALLOWED_GLOBAL_FUNCTIONS are emitted)
+    if (plannerBundle.localActionLinks) {
+        plannerBundle.localActionLinks = Array.isArray(plannerBundle.localActionLinks)
+            ? plannerBundle.localActionLinks
+            : [plannerBundle.localActionLinks];
+        const allowedFound = new Set();
+        for (const link of plannerBundle.localActionLinks) {
+            const globalName = localToGlobalAssets.get(link.genAiFunctionName);
+            if (globalName && ALLOWED_GLOBAL_FUNCTIONS.has(globalName)) {
+                allowedFound.add(globalName);
+            }
+        }
+        plannerBundle.genAiFunctions = [...allowedFound].map((genAiFunctionName) => ({ genAiFunctionName }));
+        plannerBundle.localActionLinks = [];
+    }
+    // replace references in attributeMappings and ruleExpressionAssignments
+    const attributeMappings = ensureArray(plannerBundle.attributeMappings);
+    for (const mapping of attributeMappings) {
+        if (mapping.attributeName) {
+            mapping.attributeName = replaceLocalRefsWithGlobal(mapping.attributeName, localToGlobalAssets);
+        }
+    }
+    const ruleExpressionAssignments = ensureArray(plannerBundle.ruleExpressionAssignments);
+    for (const assignment of ruleExpressionAssignments) {
+        if (assignment.targetName) {
+            assignment.targetName = replaceLocalRefsWithGlobal(assignment.targetName, localToGlobalAssets);
+        }
+    }
+    // delete local assets from the GenAiPlannerBundle
+    plannerBundle.localTopics = [];
+    plannerBundle.plannerActions = [];
+};
+/**
+ * Queries the org for asset definitions (topics or functions) and checks each local asset against the results.
+ *
+ * @returns { referenceAssetFromManagedPackage, notFoundInOrg } - The assets that are referenced from managed packages and the assets that are not found in the org
+ */
+const doValidateGlobalAssets = async (connection, toolingObject, localAssets, namespaceFromSfdxProject) => {
+    const developerNames = localAssets.map((asset) => asset.fullName).filter((name) => Boolean(name));
+    // early return if there are no local assets to validate
+    if (developerNames.length === 0) {
+        return { referenceAssetFromManagedPackage: new Set(), notFoundInOrg: new Set() };
+    }
+    const inClause = developerNames.map((name) => `'${String(name).replace(/'/g, "''")}'`).join(', ');
+    const soql = `SELECT Id, DeveloperName, NamespacePrefix, IsLocal, Source FROM ${toolingObject} WHERE DeveloperName IN (${inClause}) OR IsLocal = false`;
+    const result = await connection.tooling.query(soql);
+    const assetDefinitionResults = result.records ?? [];
+    const localAssetDefinitionResults = new Map();
+    const globalAssetDefinitionById = new Map();
+    for (const assetDefinition of assetDefinitionResults) {
+        if (assetDefinition.IsLocal) {
+            localAssetDefinitionResults.set(assetDefinition.DeveloperName, assetDefinition);
+        }
+        else {
+            globalAssetDefinitionById.set(assetDefinition.Id, assetDefinition);
+        }
+    }
+    const referenceAssetFromManagedPackage = new Set();
+    const notFoundInOrg = new Set();
+    for (const localAsset of localAssets) {
+        const currentAssetDefinitionResult = localAssetDefinitionResults.get(localAsset.fullName);
+        if (currentAssetDefinitionResult) {
+            // if source is an Id, it means it's pointing to a record created in the org
+            // if is not an Id, it means it's pointing to an standard OOTB Salesforce asset
+            if (validateSalesforceId(currentAssetDefinitionResult.Source)) {
+                const globalAsset = globalAssetDefinitionById.get(currentAssetDefinitionResult.Source);
+                if (globalAsset) {
+                    // find global assets from managed packages other than the one in the sfdx-project.json
+                    if (globalAsset.NamespacePrefix && globalAsset.NamespacePrefix !== namespaceFromSfdxProject) {
+                        referenceAssetFromManagedPackage.add(`${globalAsset.NamespacePrefix}__${globalAsset.DeveloperName}`);
+                    }
+                }
+                else {
+                    notFoundInOrg.add(currentAssetDefinitionResult.Source);
+                }
+            }
+            else {
+                // OOTB Salesforce asset, no validation needed
+            }
+        }
+        else {
+            notFoundInOrg.add(localAsset.fullName);
+        }
+    }
+    return {
+        referenceAssetFromManagedPackage,
+        notFoundInOrg,
+    };
+};
+/**
+ * Validates that local topics and actions reference global assets that exist in the source org.
+ *
+ * @param localTopics - Local genAiPlugin topics (GenAiPluginDefinition)
+ * @param localActions - Local genAiFunction actions (GenAiFunctionDefinition)
+ * @param connection - Source org connection (--source-org)
+ * @param namespaceFromSfdxProject - `namespace` from sfdx-project.json (empty if unset)
+ * @param warn - Command warn hook (e.g. `(msg) => this.warn(msg)`)
+ */
+export const validateGlobalAssets = async (localTopics, localActions, connection, namespaceFromSfdxProject, warn) => {
+    const topicsValidationResults = await doValidateGlobalAssets(connection, 'GenAiPluginDefinition', localTopics, namespaceFromSfdxProject);
+    const actionsValidationResults = await doValidateGlobalAssets(connection, 'GenAiFunctionDefinition', localActions, namespaceFromSfdxProject);
+    const referenceAssetFromManagedPackage = new Set([
+        ...topicsValidationResults.referenceAssetFromManagedPackage,
+        ...actionsValidationResults.referenceAssetFromManagedPackage,
+    ]);
+    const notFoundInOrg = new Set([
+        ...topicsValidationResults.notFoundInOrg,
+        ...actionsValidationResults.notFoundInOrg,
+    ]);
+    if (referenceAssetFromManagedPackage.size > 0) {
+        warn(messages.getMessage('warn.reference-asset-from-managed-package', [
+            [...referenceAssetFromManagedPackage].join(', '),
+        ]));
+    }
+    if (notFoundInOrg.size > 0) {
+        throw new SfError(messages.getMessage('error.global-asset-not-found', [[...notFoundInOrg].join(', ')]));
+    }
+};
+/**
+ * Builds a map from local asset names to their global (source) asset names.
+ *
+ * @param localTopics - The local topics of the GenAiPlannerBundle
+ * @param plannerBundle - The GenAiPlannerBundle (for plannerActions)
+ * @returns A map of local asset name → global asset name
+ */
+const buildLocalToGlobalAssetMap = (localTopics, plannerBundle) => {
+    const map = new Map();
+    for (const topic of localTopics) {
+        map.set(topic.fullName, topic.source);
+        const actions = Array.isArray(topic.localActions)
+            ? topic.localActions
+            : topic.localActions
+                ? [topic.localActions]
+                : [];
+        for (const action of actions) {
+            map.set(action.fullName, action.source);
+        }
+    }
+    const plannerActions = Array.isArray(plannerBundle.plannerActions)
+        ? plannerBundle.plannerActions
+        : plannerBundle.plannerActions
+            ? [plannerBundle.plannerActions]
+            : [];
+    for (const action of plannerActions) {
+        if (action.fullName && action.source)
+            map.set(action.fullName, action.source);
+    }
+    return map;
+};
+/**
+ * Replaces dot-separated local refs with global names. Each segment is replaced only when present in localToGlobalMap;
+ * segments not in localToGlobalMap (e.g. namespace, attribute path) are kept as-is. Used for attributeName, targetName, expression.
+ */
+const replaceLocalRefsWithGlobal = (value, localToGlobalMap) => value
+    .split('.')
+    .map((segment) => localToGlobalMap.get(segment) ?? segment)
+    .join('.');
+/**
+ * Copies metadata directories from the source package (basePath) to the output directory if they exist.
+ * Source path is derived from the agent file location (e.g. force-app/main/default).
+ */
+const copyMetadataDirsIfPresent = (basePath, outputBase) => {
+    const METADATA_DIRS_TO_COPY = ['genAiPlugins', 'genAiFunctions', 'classes', 'flows', 'genAiPromptTemplates'];
+    const copiedDirs = [];
+    for (const dirName of METADATA_DIRS_TO_COPY) {
+        const srcDir = join(basePath, dirName);
+        if (existsSync(srcDir) && statSync(srcDir).isDirectory()) {
+            const destDir = join(outputBase, dirName);
+            cpSync(srcDir, destDir, { recursive: true });
+            copiedDirs.push(dirName);
+        }
     }
+    return copiedDirs;
 };
 //# sourceMappingURL=template.js.map