@salesforce/plugin-agent 1.32.15 → 1.32.16

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.15/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/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.15/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/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.15/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/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.15/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.16/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.15/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.16/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.15/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/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.15/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.16/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.15/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -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.15/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -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.15/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/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.15/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -773,7 +773,7 @@ Start a programmatic agent preview session.
 ```
 USAGE
   $ sf agent preview start -o <value> [--json] [--flags-dir <value>] [--api-version <value>] [-n <value>]
-    [--authoring-bundle <value>] [--use-live-actions]
+    [--authoring-bundle <value>] [--use-live-actions | --simulate-actions]
 
 FLAGS
   -n, --api-name=<value>          API name of the activated published agent you want to preview.
@@ -782,8 +782,10 @@ FLAGS
       --api-version=<value>       Override the api version used for api requests made by this command
       --authoring-bundle=<value>  API name of the authoring bundle metadata component that contains the agent's Agent
                                   Script file.
-      --use-live-actions          Use real actions in the org; if not specified, preview uses AI to simulate (mock)
-                                  actions.
+      --simulate-actions          Use AI to simulate action execution instead of calling real actions. Required with
+                                  --authoring-bundle.
+      --use-live-actions          Execute real actions in the org (Apex classes, flows, etc.). Required with
+                                  --authoring-bundle.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
@@ -802,26 +804,32 @@ DESCRIPTION
   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,
-  etc, in the org for the actions.
+  When starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of
+  these flags:
+
+  - --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and
+  validation errors during preview.
+  - --simulate-actions: Uses AI to simulate action execution without calling real implementations.
+
+  Published agents (--api-name) always use live actions. The mode flags are optional and have no effect for published
+  agents.
 
 EXAMPLES
-  Start a programmatic agent preview session by specifying an authoring bundle; uses mocked actions by default. Use
-  the org with alias "my-dev-org":
+  Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org
+  with alias "my-dev-org":
 
-    $ sf agent preview start --authoring-bundle My_Agent_Bundle --target-org my-dev-org
+    $ sf agent preview start --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions
 
   Similar to previous example but use live actions and the default org:
 
     $ sf agent preview start --authoring-bundle My_Agent_Bundle --use-live-actions
 
-  Start a preview session with an activated published agent:
+  Start a preview session with an activated published agent (always uses live actions):
 
     $ 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.15/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -870,7 +878,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.15/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.16/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -925,7 +933,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.15/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -960,7 +968,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.15/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -1026,7 +1034,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.15/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1099,7 +1107,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.15/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1173,7 +1181,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.15/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.32.16/src/commands/agent/test/run.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1220,6 +1228,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.15/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.16/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

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

@@ -15,6 +15,7 @@ export default class AgentPreviewStart extends SfCommand<AgentPreviewStartResult
         'api-name': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'authoring-bundle': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'use-live-actions': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'simulate-actions': import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<AgentPreviewStartResult>;
 }

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

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { Flags, SfCommand, toHelpSection } from '@salesforce/sf-plugins-core';
-import { Lifecycle, Messages, SfError, EnvironmentVariable } from '@salesforce/core';
+import { EnvironmentVariable, Lifecycle, Messages, SfError } from '@salesforce/core';
 import { Agent, ProductionAgent, ScriptAgent } from '@salesforce/agents';
 import { createCache } from '../../../previewSessionStore.js';
 import { COMPILATION_API_EXIT_CODES } from '../../../common.js';
@@ -47,13 +47,23 @@ export default class AgentPreviewStart extends SfCommand {
         }),
         'use-live-actions': Flags.boolean({
             summary: messages.getMessage('flags.use-live-actions.summary'),
-            default: false,
+            exclusive: ['simulate-actions'],
+        }),
+        'simulate-actions': Flags.boolean({
+            summary: messages.getMessage('flags.simulate-actions.summary'),
+            exclusive: ['use-live-actions'],
         }),
     };
     async run() {
         const { flags } = await this.parse(AgentPreviewStart);
+        // Validate: authoring-bundle requires exactly one mode flag
+        // (mutual exclusion of mode flags handled by 'exclusive' in flag definitions)
+        if (flags['authoring-bundle'] && !flags['use-live-actions'] && !flags['simulate-actions']) {
+            throw new SfError('When using --authoring-bundle, you must specify either --use-live-actions or --simulate-actions.', 'MissingModeFlag');
+        }
         const conn = flags['target-org'].getConnection(flags['api-version']);
         const useLiveActions = flags['use-live-actions'];
+        const simulateActions = flags['simulate-actions'];
         const agentIdentifier = flags['authoring-bundle'] ?? flags['api-name'];
         // Track telemetry for agent initialization
         let agent;
@@ -87,11 +97,14 @@ export default class AgentPreviewStart extends SfCommand {
             await Lifecycle.getInstance().emitTelemetry({ eventName: 'agent_preview_start_agent_init_failed' });
             throw wrapped;
         }
+        // Set mode for authoring bundles based on which flag was specified
+        // (mutual exclusion enforced by flag definitions - can't have both)
         if (agent instanceof ScriptAgent) {
-            agent.preview.setMockMode(useLiveActions ? 'Live Test' : 'Mock');
+            agent.preview.setMockMode(simulateActions ? 'Mock' : 'Live Test');
         }
-        if (useLiveActions && agent instanceof ProductionAgent) {
-            void Lifecycle.getInstance().emitWarning('Published agents always use real actions; --use-live-actions has no effect for published agents.');
+        // Warn if mode flags are used with published agents (they have no effect)
+        if (agent instanceof ProductionAgent && (useLiveActions || simulateActions)) {
+            void Lifecycle.getInstance().emitWarning('Published agents always use real actions; --use-live-actions and --simulate-actions have no effect for published agents.');
         }
         // Track telemetry for preview start
         let session;

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

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

package/messages/agent.preview.start.md

@@ -8,7 +8,12 @@ This command outputs a session ID that you then use with the "agent preview send
 
 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 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.
 
-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, etc, in the org for the actions.
+When starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:
+
+- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.
+- --simulate-actions: Uses AI to simulate action execution without calling real implementations.
+
+Published agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.
 
 # flags.api-name.summary
 
@@ -20,7 +25,11 @@ API name of the authoring bundle metadata component that contains the agent's Ag
 
 # flags.use-live-actions.summary
 
-Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions.
+Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.
+
+# flags.simulate-actions.summary
+
+Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.
 
 # output.sessionId
 
@@ -40,14 +49,14 @@ Failed to start preview session: %s
 
 # examples
 
-- Start a programmatic agent preview session by specifying an authoring bundle; uses mocked actions by default. Use the org with alias "my-dev-org":
+- Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias "my-dev-org":
 
-  <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org
+  <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions
 
 - Similar to previous example but use live actions and the default org:
 
   <%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions
 
-- Start a preview session with an activated published agent:
+- Start a preview session with an activated published agent (always uses live actions):
 
   <%= config.bin %> <%= command.id %> --api-name My_Published_Agent

package/oclif.manifest.json

@@ -1189,11 +1189,11 @@
     "agent:preview:start": {
       "aliases": [],
       "args": {},
-      "description": "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.\n\nIdentify 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 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.\n\nWhen 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, etc, in the org for the actions.",
+      "description": "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.\n\nIdentify 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 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.\n\nWhen starting a preview session with --authoring-bundle, you must explicitly specify the execution mode using one of these flags:\n\n- --use-live-actions: Executes real Apex classes, flows, and other actions in the org. This surfaces compile and validation errors during preview.\n- --simulate-actions: Uses AI to simulate action execution without calling real implementations.\n\nPublished agents (--api-name) always use live actions. The mode flags are optional and have no effect for published agents.",
       "examples": [
-        "Start a programmatic agent preview session by specifying an authoring bundle; uses mocked actions by default. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org",
+        "Start a programmatic agent preview session by specifying an authoring bundle; use simulated actions. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --target-org my-dev-org --simulate-actions",
         "Similar to previous example but use live actions and the default org:\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Agent_Bundle --use-live-actions",
-        "Start a preview session with an activated published agent:\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
+        "Start a preview session with an activated published agent (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
       ],
       "flags": {
         "json": {
@@ -1244,8 +1244,20 @@
           "type": "option"
         },
         "use-live-actions": {
+          "exclusive": [
+            "simulate-actions"
+          ],
           "name": "use-live-actions",
-          "summary": "Use real actions in the org; if not specified, preview uses AI to simulate (mock) actions.",
+          "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "simulate-actions": {
+          "exclusive": [
+            "use-live-actions"
+          ],
+          "name": "simulate-actions",
+          "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
           "allowNo": false,
           "type": "boolean"
         }
@@ -2328,5 +2340,5 @@
       ]
     }
   },
-  "version": "1.32.15"
+  "version": "1.32.16"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@salesforce/plugin-agent",
     "description": "Commands to interact with Salesforce agents",
-    "version": "1.32.15",
+    "version": "1.32.16",
     "author": "Salesforce",
     "bugs": "https://github.com/forcedotcom/cli/issues",
     "enableO11y": true,
@@ -240,7 +240,7 @@
     "exports": "./lib/index.js",
     "type": "module",
     "sfdx": {
-        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.32.15.crt",
-        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.32.15.sig"
+        "publicKeyUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.32.16.crt",
+        "signatureUrl": "https://developer.salesforce.com/media/salesforce-cli/security/@salesforce/plugin-agent/1.32.16.sig"
     }
 }