@salesforce/plugin-agent 1.32.13 → 1.32.15

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.13/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/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.13/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/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.13/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/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.13/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.15/src/commands/agent/generate/agent-spec.ts)_
 
 ## `sf agent generate authoring-bundle`
 
@@ -418,7 +418,7 @@ 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.13/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.15/src/commands/agent/generate/authoring-bundle.ts)_
 
 ## `sf agent generate template`
 
@@ -480,7 +480,7 @@ EXAMPLES
       my-package --source-org my-scratch-org
 ```
 
-_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.13/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/generate/template.ts)_
 
 ## `sf agent generate test-spec`
 
@@ -545,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.13/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.15/src/commands/agent/generate/test-spec.ts)_
 
 ## `sf agent preview`
 
@@ -618,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.13/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -650,11 +650,11 @@ DESCRIPTION
   use this command to end it. This command also displays the local directory where the session trace files are stored.
 
   The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this
-  command to end the session.  You don't have to specify the --session-id flag if an agent has only one active preview
+  command to end the session. You don't have to specify the --session-id flag if an agent has only one active preview
   session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring
-  bundle or the published agent, respecitvely.  To find either API name, navigate to your package directory in your DX
+  bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX
   project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata
-  directory.  Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata
+  directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata
   directory.
 
 EXAMPLES
@@ -673,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.13/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -706,11 +706,11 @@ DESCRIPTION
   use this command to send the agent a message (utterance). This command then displays the agent's response.
 
   The original "agent preview start" command outputs a session ID which you then use with the --session-id flag of this
-  command to send a message.  You don't have to specify the --session-id flag if an agent has only one active preview
+  command to send a message. You don't have to specify the --session-id flag if an agent has only one active preview
   session. You must also use either the --authoring-bundle or --api-name flag to specify the API name of the authoring
-  bundle or the published agent, respecitvely.  To find either API name, navigate to your package directory in your DX
+  bundle or the published agent, respecitvely. To find either API name, navigate to your package directory in your DX
   project. The API name of an authoring bundle is the same as its directory name under the "aiAuthoringBundles" metadata
-  directory.  Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata
+  directory. Similarly, the published agent's API name is the same as its directory name under the "Bots" metadata
   directory.
 
 EXAMPLES
@@ -731,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.13/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/preview/send.ts)_
 
 ## `sf agent preview sessions`
 
@@ -764,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.13/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -793,17 +793,17 @@ DESCRIPTION
   Start a programmatic agent preview session.
 
   This command outputs a session ID that you then use with the "agent preview send" command to send an utterance to the
-  agent.  Use the "agent preview sessions" command to list all active sessions and the "agent preview end" command to
-  end a specific session.
+  agent. Use the "agent preview sessions" command to list all active sessions and the "agent preview end" command to end
+  a specific session.
 
   Identify the agent you want to start previewing with either the --authoring-bundle flag to specify a local authoring
-  bundle's API name or --api-name to specify an activated published agent's API name.  To find either API name, navigate
+  bundle's API name or --api-name to specify an activated published agent's API name. To find either API name, navigate
   to your package directory in your DX project. The API name of an authoring bundle is the same as its directory name
-  under the "aiAuthoringBundles" metadata directory.  Similarly, the published agent's API name is the same as its
+  under the "aiAuthoringBundles" metadata directory. Similarly, the published agent's API name is the same as its
   directory name under the "Bots" metadata directory.
 
   When starting a preview session using the authoring bundle, which contains the agent's Agent Script file, the preview
-  uses mocked actions by default.  Specify --use-live-actions for live mode, which uses the real Apex classes, flows,
+  uses mocked actions by default. Specify --use-live-actions for live mode, which uses the real Apex classes, flows,
   etc, in the org for the actions.
 
 EXAMPLES
@@ -821,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.13/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -870,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.13/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.15/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -925,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.13/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -960,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.13/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -1026,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.13/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1099,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.13/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1173,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.13/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.15/src/commands/agent/test/run.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1220,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.13/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.15/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

package/lib/commands/agent/activate.d.ts

@@ -8,6 +8,8 @@ export default class AgentActivate extends SfCommand<AgentActivateResult> {
     static readonly description: string;
     static readonly examples: string[];
     static readonly enableJsonFlag = true;
+    static readonly envVariablesSection: import("@oclif/core").HelpSection;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
     static readonly flags: {
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/agent/activate.js

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
-import { Messages } from '@salesforce/core';
+import { SfCommand, Flags, toHelpSection } from '@salesforce/sf-plugins-core';
+import { Messages, SfError, Lifecycle, EnvironmentVariable } from '@salesforce/core';
 import { getAgentForActivation, getVersionForActivation } from '../../agentActivation.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.activate');
@@ -23,6 +23,12 @@ export default class AgentActivate extends SfCommand {
     static description = messages.getMessage('description');
     static examples = messages.getMessages('examples');
     static enableJsonFlag = true;
+    static envVariablesSection = toHelpSection('ENVIRONMENT VARIABLES', EnvironmentVariable.SF_TARGET_ORG);
+    static errorCodes = toHelpSection('ERROR CODES', {
+        'Succeeded (0)': 'Agent activated successfully.',
+        'NotFound (2)': 'Agent not found in the org.',
+        'ActivationFailed (4)': 'Failed to activate the agent due to API or network errors.',
+    });
     static flags = {
         'target-org': Flags.requiredOrg(),
         'api-version': Flags.orgApiVersion(),
@@ -39,15 +45,38 @@ export default class AgentActivate extends SfCommand {
         if (!apiNameFlag && this.jsonEnabled()) {
             throw messages.createError('error.missingRequiredFlags', ['api-name']);
         }
-        const agent = await getAgentForActivation({ targetOrg, status: 'Active', apiNameFlag });
+        // Get agent with error tracking
+        let agent;
+        try {
+            agent = await getAgentForActivation({ targetOrg, status: 'Active', apiNameFlag });
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            if (wrapped.message.toLowerCase().includes('not found') || wrapped.message.toLowerCase().includes('no agent')) {
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_activate_agent_not_found' });
+                throw new SfError(messages.getMessage('error.agentNotFound', [apiNameFlag ?? 'unknown']), 'AgentNotFound', [], 2, wrapped);
+            }
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_activate_get_agent_failed' });
+            throw wrapped;
+        }
         const { version, warning } = await getVersionForActivation({
             agent,
             status: 'Active',
             versionFlag: flags.version,
             jsonEnabled: this.jsonEnabled(),
         });
-        const result = await agent.activate(version);
+        // Activate with error tracking
+        let result;
+        try {
+            result = await agent.activate(version);
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_activate_failed' });
+            throw new SfError(messages.getMessage('error.activationFailed', [wrapped.message]), 'ActivationFailed', [wrapped.message], 4, wrapped);
+        }
         const metadata = await agent.getBotMetadata();
+        await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_activate_success' });
         this.log(`${metadata.DeveloperName} v${result.VersionNumber} activated.`);
         if (warning) {
             this.warn(warning);

package/lib/commands/agent/activate.js.map

@@ -1 +1 @@
-{"version":3,"file":"activate.js","sourceRoot":"","sources":["../../../src/commands/agent/activate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAI1F,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,0BAA0B,EAAE,gBAAgB,CAAC,CAAC;AAErF,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,SAA8B;IAChE,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAC5D,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAU,KAAK,GAAG;QAC7B,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE;QACjC,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE;QACpC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;YACvB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;YACtD,IAAI,EAAE,GAAG;SACV,CAAC;QACF,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,uBAAuB,CAAC,EAAE,CAAC;KAClF,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAElD,MAAM,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QAEtC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvC,MAAM,QAAQ,CAAC,WAAW,CAAC,4BAA4B,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;QACxF,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,uBAAuB,CAAC;YACzD,KAAK;YACL,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,KAAK,CAAC,OAAO;YAC1B,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;SAChC,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;QAE9C,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,aAAa,KAAK,MAAM,CAAC,aAAa,aAAa,CAAC,CAAC;QAC1E,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;IAC1D,CAAC"}
+{"version":3,"file":"activate.js","sourceRoot":"","sources":["../../../src/commands/agent/activate.ts"],"names":[],"mappings":"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"}

package/lib/commands/agent/deactivate.d.ts

@@ -5,6 +5,8 @@ export default class AgentDeactivate extends SfCommand<AgentActivateResult> {
     static readonly description: string;
     static readonly examples: string[];
     static enableJsonFlag: boolean;
+    static readonly envVariablesSection: import("@oclif/core").HelpSection;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
     static readonly flags: {
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/agent/deactivate.js

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
-import { Messages } from '@salesforce/core';
+import { SfCommand, Flags, toHelpSection } from '@salesforce/sf-plugins-core';
+import { Messages, SfError, Lifecycle, EnvironmentVariable } from '@salesforce/core';
 import { getAgentForActivation } from '../../agentActivation.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.deactivate');
@@ -23,6 +23,12 @@ export default class AgentDeactivate extends SfCommand {
     static description = messages.getMessage('description');
     static examples = messages.getMessages('examples');
     static enableJsonFlag = true;
+    static envVariablesSection = toHelpSection('ENVIRONMENT VARIABLES', EnvironmentVariable.SF_TARGET_ORG);
+    static errorCodes = toHelpSection('ERROR CODES', {
+        'Succeeded (0)': 'Agent deactivated successfully.',
+        'NotFound (2)': 'Agent not found in the org.',
+        'DeactivationFailed (4)': 'Failed to deactivate the agent due to API or network errors.',
+    });
     static flags = {
         'target-org': Flags.requiredOrg(),
         'api-version': Flags.orgApiVersion(),
@@ -38,9 +44,32 @@ export default class AgentDeactivate extends SfCommand {
         if (!apiNameFlag && this.jsonEnabled()) {
             throw messages.createError('error.missingRequiredFlags', ['api-name']);
         }
-        const agent = await getAgentForActivation({ targetOrg, status: 'Inactive', apiNameFlag });
-        const result = await agent.deactivate();
+        // Get agent with error tracking
+        let agent;
+        try {
+            agent = await getAgentForActivation({ targetOrg, status: 'Inactive', apiNameFlag });
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            if (wrapped.message.toLowerCase().includes('not found') || wrapped.message.toLowerCase().includes('no agent')) {
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_deactivate_agent_not_found' });
+                throw new SfError(messages.getMessage('error.agentNotFound', [apiNameFlag ?? 'unknown']), 'AgentNotFound', [], 2, wrapped);
+            }
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_deactivate_get_agent_failed' });
+            throw wrapped;
+        }
+        // Deactivate with error tracking
+        let result;
+        try {
+            result = await agent.deactivate();
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_deactivate_failed' });
+            throw new SfError(messages.getMessage('error.deactivationFailed', [wrapped.message]), 'DeactivationFailed', [wrapped.message], 4, wrapped);
+        }
         const metadata = await agent.getBotMetadata();
+        await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_deactivate_success' });
         this.log(`${metadata.DeveloperName} v${result.VersionNumber} deactivated.`);
         return { success: true, version: result.VersionNumber };
     }

package/lib/commands/agent/deactivate.js.map

@@ -1 +1 @@
-{"version":3,"file":"deactivate.js","sourceRoot":"","sources":["../../../src/commands/agent/deactivate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,0BAA0B,EAAE,kBAAkB,CAAC,CAAC;AAEvF,MAAM,CAAC,OAAO,OAAO,eAAgB,SAAQ,SAA8B;IAClE,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAC5D,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IAE7B,MAAM,CAAU,KAAK,GAAG;QAC7B,YAAY,EAAE,KAAK,CAAC,WAAW,EAAE;QACjC,aAAa,EAAE,KAAK,CAAC,aAAa,EAAE;QACpC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;YACvB,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,wBAAwB,CAAC;YACtD,IAAI,EAAE,GAAG;SACV,CAAC;KACH,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAEpD,MAAM,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QAEtC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACvC,MAAM,QAAQ,CAAC,WAAW,CAAC,4BAA4B,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,qBAAqB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC;QAC1F,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,cAAc,EAAE,CAAC;QAE9C,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,aAAa,KAAK,MAAM,CAAC,aAAa,eAAe,CAAC,CAAC;QAC5E,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;IAC1D,CAAC"}
+{"version":3,"file":"deactivate.js","sourceRoot":"","sources":["../../../src/commands/agent/deactivate.ts"],"names":[],"mappings":"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"}

package/lib/commands/agent/preview/end.d.ts

@@ -8,6 +8,8 @@ export default class AgentPreviewEnd extends SfCommand<AgentPreviewEndResult> {
     static readonly description: string;
     static readonly examples: string[];
     static readonly requiresProject = true;
+    static readonly envVariablesSection: import("@oclif/core").HelpSection;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
     static readonly flags: {
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/agent/preview/end.js

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
-import { Messages, SfError } from '@salesforce/core';
+import { Flags, SfCommand, toHelpSection } from '@salesforce/sf-plugins-core';
+import { Messages, SfError, Lifecycle, EnvironmentVariable } from '@salesforce/core';
 import { Agent, ProductionAgent, ScriptAgent } from '@salesforce/agents';
 import { getCachedSessionIds, removeCache, validatePreviewSession } from '../../../previewSessionStore.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
@@ -24,6 +24,13 @@ export default class AgentPreviewEnd extends SfCommand {
     static description = messages.getMessage('description');
     static examples = messages.getMessages('examples');
     static requiresProject = true;
+    static envVariablesSection = toHelpSection('ENVIRONMENT VARIABLES', EnvironmentVariable.SF_TARGET_ORG);
+    static errorCodes = toHelpSection('ERROR CODES', {
+        'Succeeded (0)': 'Preview session ended successfully and traces saved.',
+        'NotFound (2)': 'Agent not found, or no preview session exists for this agent.',
+        'PreviewEndFailed (4)': 'Failed to end the preview session.',
+        'SessionAmbiguous (5)': 'Multiple preview sessions found; specify --session-id to choose one.',
+    });
     static flags = {
         'target-org': Flags.requiredOrg(),
         'api-version': Flags.orgApiVersion(),
@@ -44,30 +51,60 @@ export default class AgentPreviewEnd extends SfCommand {
     async run() {
         const { flags } = await this.parse(AgentPreviewEnd);
         const conn = flags['target-org'].getConnection(flags['api-version']);
-        const agent = flags['authoring-bundle']
-            ? await Agent.init({ connection: conn, project: this.project, aabName: flags['authoring-bundle'] })
-            : await Agent.init({ connection: conn, project: this.project, apiNameOrId: flags['api-name'] });
+        const agentIdentifier = flags['authoring-bundle'] ?? flags['api-name'];
+        // Initialize agent with error tracking
+        let agent;
+        try {
+            agent = flags['authoring-bundle']
+                ? await Agent.init({ connection: conn, project: this.project, aabName: flags['authoring-bundle'] })
+                : await Agent.init({ connection: conn, project: this.project, apiNameOrId: flags['api-name'] });
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_agent_not_found' });
+            throw new SfError(messages.getMessage('error.agentNotFound', [agentIdentifier]), 'AgentNotFound', [], 2, wrapped);
+        }
+        // Get or validate session ID
         let sessionId = flags['session-id'];
         if (sessionId === undefined) {
             const cached = await getCachedSessionIds(this.project, agent);
             if (cached.length === 0) {
-                throw new SfError(messages.getMessage('error.noSession'), 'PreviewSessionNotFound');
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_no_session' });
+                throw new SfError(messages.getMessage('error.noSession'), 'PreviewSessionNotFound', [], 2);
             }
             if (cached.length > 1) {
-                throw new SfError(messages.getMessage('error.multipleSessions', [cached.join(', ')]), 'PreviewSessionAmbiguous');
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_multiple_sessions' });
+                throw new SfError(messages.getMessage('error.multipleSessions', [cached.join(', ')]), 'PreviewSessionAmbiguous', [], 5);
             }
             sessionId = cached[0];
         }
         agent.setSessionId(sessionId);
-        await validatePreviewSession(agent);
+        // Validate session
+        try {
+            await validatePreviewSession(agent);
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_session_invalid' });
+            throw new SfError(messages.getMessage('error.sessionInvalid', [sessionId]), 'PreviewSessionInvalid', [], 2, wrapped);
+        }
         const tracesPath = await agent.getHistoryDir();
         await removeCache(agent);
-        if (agent instanceof ScriptAgent) {
-            await agent.preview.end();
+        // End preview with error tracking
+        try {
+            if (agent instanceof ScriptAgent) {
+                await agent.preview.end();
+            }
+            else if (agent instanceof ProductionAgent) {
+                await agent.preview.end('UserRequest');
+            }
         }
-        else if (agent instanceof ProductionAgent) {
-            await agent.preview.end('UserRequest');
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_failed' });
+            throw new SfError(messages.getMessage('error.endFailed', [wrapped.message]), 'PreviewEndFailed', [wrapped.message], 4, wrapped);
         }
+        await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_end_success' });
         const result = { sessionId, tracesPath };
         this.log(messages.getMessage('output.tracesPath', [tracesPath]));
         return result;

package/lib/commands/agent/preview/end.js.map

@@ -1 +1 @@
-{"version":3,"file":"end.js","sourceRoot":"","sources":["../../../../src/commands/agent/preview/end.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"end.js","sourceRoot":"","sources":["../../../../src/commands/agent/preview/end.ts"],"names":[],"mappings":"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"}

package/lib/commands/agent/preview/send.d.ts

@@ -10,6 +10,8 @@ export default class AgentPreviewSend extends SfCommand<AgentPreviewSendResult>
     static readonly description: string;
     static readonly examples: string[];
     static readonly requiresProject = true;
+    static readonly envVariablesSection: import("@oclif/core").HelpSection;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
     static readonly flags: {
         'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
         'api-version': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/lib/commands/agent/preview/send.js

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Flags, SfCommand } from '@salesforce/sf-plugins-core';
-import { Messages, SfError } from '@salesforce/core';
+import { Flags, SfCommand, toHelpSection } from '@salesforce/sf-plugins-core';
+import { Messages, SfError, Lifecycle, EnvironmentVariable } from '@salesforce/core';
 import { Agent } from '@salesforce/agents';
 import { getCachedSessionIds, validatePreviewSession } from '../../../previewSessionStore.js';
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
@@ -24,6 +24,13 @@ export default class AgentPreviewSend extends SfCommand {
     static description = messages.getMessage('description');
     static examples = messages.getMessages('examples');
     static requiresProject = true;
+    static envVariablesSection = toHelpSection('ENVIRONMENT VARIABLES', EnvironmentVariable.SF_TARGET_ORG);
+    static errorCodes = toHelpSection('ERROR CODES', {
+        'Succeeded (0)': 'Message sent successfully and agent response received.',
+        'NotFound (2)': 'Agent not found, or no preview session exists for this agent.',
+        'PreviewSendFailed (4)': 'Failed to send message or receive response from the preview session.',
+        'SessionAmbiguous (5)': 'Multiple preview sessions found; specify --session-id to choose one.',
+    });
     static flags = {
         'target-org': Flags.requiredOrg(),
         'api-version': Flags.orgApiVersion(),
@@ -49,23 +56,54 @@ export default class AgentPreviewSend extends SfCommand {
     async run() {
         const { flags } = await this.parse(AgentPreviewSend);
         const conn = flags['target-org'].getConnection(flags['api-version']);
-        const agent = flags['authoring-bundle']
-            ? await Agent.init({ connection: conn, project: this.project, aabName: flags['authoring-bundle'] })
-            : await Agent.init({ connection: conn, project: this.project, apiNameOrId: flags['api-name'] });
+        const agentIdentifier = flags['authoring-bundle'] ?? flags['api-name'];
+        // Initialize agent with error tracking
+        let agent;
+        try {
+            agent = flags['authoring-bundle']
+                ? await Agent.init({ connection: conn, project: this.project, aabName: flags['authoring-bundle'] })
+                : await Agent.init({ connection: conn, project: this.project, apiNameOrId: flags['api-name'] });
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_agent_not_found' });
+            throw new SfError(messages.getMessage('error.agentNotFound', [agentIdentifier]), 'AgentNotFound', [], 2, wrapped);
+        }
+        // Get or validate session ID
         let sessionId = flags['session-id'];
         if (sessionId === undefined) {
             const cached = await getCachedSessionIds(this.project, agent);
             if (cached.length === 0) {
-                throw new SfError(messages.getMessage('error.noSession'), 'PreviewSessionNotFound');
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_no_session' });
+                throw new SfError(messages.getMessage('error.noSession'), 'PreviewSessionNotFound', [], 2);
             }
             if (cached.length > 1) {
-                throw new SfError(messages.getMessage('error.multipleSessions', [cached.join(', ')]), 'PreviewSessionAmbiguous');
+                await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_multiple_sessions' });
+                throw new SfError(messages.getMessage('error.multipleSessions', [cached.join(', ')]), 'PreviewSessionAmbiguous', [], 5);
             }
             sessionId = cached[0];
         }
         agent.setSessionId(sessionId);
-        await validatePreviewSession(agent);
-        const response = await agent.preview.send(flags.utterance);
+        // Validate session
+        try {
+            await validatePreviewSession(agent);
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_session_invalid' });
+            throw new SfError(messages.getMessage('error.sessionInvalid', [sessionId]), 'PreviewSessionInvalid', [], 2, wrapped);
+        }
+        // Send message with error tracking
+        let response;
+        try {
+            response = await agent.preview.send(flags.utterance);
+        }
+        catch (error) {
+            const wrapped = SfError.wrap(error);
+            await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_failed' });
+            throw new SfError(messages.getMessage('error.sendFailed', [wrapped.message]), 'PreviewSendFailed', [wrapped.message], 4, wrapped);
+        }
+        await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_send_success' });
         this.log(response.messages[0].message);
         return { messages: response.messages ?? [] };
     }