@salesforce/plugin-agent 1.37.0 → 1.38.0

package/oclif.manifest.json

@@ -409,6 +409,473 @@
         "preview:agent"
       ]
     },
+    "agent:preview:end": {
+      "aliases": [],
+      "args": {},
+      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe 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 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 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.",
+      "examples": [
+        "End a preview session of a published agent by specifying its session ID and API name ; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
+        "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
+        "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:preview:end",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "End an existing programmatic agent preview session and get trace location.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "envVariablesSection": {
+        "header": "ENVIRONMENT VARIABLES",
+        "body": [
+          {
+            "name": "SF_TARGET_ORG",
+            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
+          }
+        ]
+      },
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Preview session ended successfully and traces saved."
+          },
+          {
+            "name": "NotFound (2)",
+            "description": "Agent not found, or no preview session exists for this agent."
+          },
+          {
+            "name": "PreviewEndFailed (4)",
+            "description": "Failed to end the preview session."
+          },
+          {
+            "name": "SessionAmbiguous (5)",
+            "description": "Multiple preview sessions found; specify --session-id to choose one."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "end.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:end",
+        "preview:agent:end",
+        "preview:end:agent",
+        "agent:end:preview",
+        "end:agent:preview",
+        "end:preview:agent"
+      ]
+    },
+    "agent:preview:send": {
+      "aliases": [],
+      "args": {},
+      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe 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 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 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.",
+      "examples": [
+        "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
+        "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
+        "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "session-id": {
+          "name": "session-id",
+          "required": false,
+          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "utterance": {
+          "char": "u",
+          "name": "utterance",
+          "required": true,
+          "summary": "Utterance to send to the agent, enclosed in double quotes.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:preview:send",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Send a message to an existing agent preview session.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "envVariablesSection": {
+        "header": "ENVIRONMENT VARIABLES",
+        "body": [
+          {
+            "name": "SF_TARGET_ORG",
+            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
+          }
+        ]
+      },
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Message sent successfully and agent response received."
+          },
+          {
+            "name": "NotFound (2)",
+            "description": "Agent not found, or no preview session exists for this agent."
+          },
+          {
+            "name": "PreviewSendFailed (4)",
+            "description": "Failed to send message or receive response from the preview session."
+          },
+          {
+            "name": "SessionAmbiguous (5)",
+            "description": "Multiple preview sessions found; specify --session-id to choose one."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "send.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:send",
+        "preview:agent:send",
+        "preview:send:agent",
+        "agent:send:preview",
+        "send:agent:preview",
+        "send:preview:agent"
+      ]
+    },
+    "agent:preview:sessions": {
+      "aliases": [],
+      "args": {},
+      "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
+      "examples": [
+        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:preview:sessions",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "List all known programmatic agent preview sessions.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Sessions listed successfully (or empty list if no active sessions)."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "sessions.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:sessions",
+        "preview:agent:sessions",
+        "preview:sessions:agent",
+        "agent:sessions:preview",
+        "sessions:agent:preview",
+        "sessions:preview:agent"
+      ]
+    },
+    "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 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; 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 (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "flags-dir": {
+          "helpGroup": "GLOBAL",
+          "name": "flags-dir",
+          "summary": "Import flag values from a directory.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "target-org": {
+          "char": "o",
+          "name": "target-org",
+          "noCacheDefault": true,
+          "required": true,
+          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
+          "hasDynamicHelp": true,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-version": {
+          "description": "Override the api version used for api requests made by this command",
+          "name": "api-version",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-name": {
+          "char": "n",
+          "name": "api-name",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "name": "authoring-bundle",
+          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "use-live-actions": {
+          "exclusive": [
+            "simulate-actions"
+          ],
+          "name": "use-live-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"
+        },
+        "agent-json": {
+          "dependsOn": [
+            "authoring-bundle"
+          ],
+          "hidden": true,
+          "name": "agent-json",
+          "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": true,
+      "hiddenAliases": [],
+      "id": "agent:preview:start",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Start a programmatic agent preview session.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "envVariablesSection": {
+        "header": "ENVIRONMENT VARIABLES",
+        "body": [
+          {
+            "name": "SF_TARGET_ORG",
+            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
+          }
+        ]
+      },
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Preview session started successfully."
+          },
+          {
+            "name": "Failed (1)",
+            "description": "Agent Script compilation failed (syntax errors in the script)."
+          },
+          {
+            "name": "NotFound (2)",
+            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
+          },
+          {
+            "name": "ServerError (3)",
+            "description": "Compilation API returned HTTP 500 (server error during compilation)."
+          },
+          {
+            "name": "PreviewStartFailed (4)",
+            "description": "Preview session failed to start due to API or network errors."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "preview",
+        "start.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:preview:start",
+        "preview:agent:start",
+        "preview:start:agent",
+        "agent:start:preview",
+        "start:agent:preview",
+        "start:preview:agent"
+      ]
+    },
     "agent:generate:agent-spec": {
       "aliases": [],
       "args": {},
@@ -1764,157 +2231,33 @@
         },
         "test-runner": {
           "description": "By default, the command automatically detects which test runner to use based on the test definition metadata type in your org. Use this flag to explicitly specify the runner type. 'agentforce-studio' uses AiTestingDefinition metadata. 'testing-center' uses AiEvaluationDefinition metadata.",
-          "name": "test-runner",
-          "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "agentforce-studio",
-            "testing-center"
-          ],
-          "type": "option"
-        },
-        "verbose": {
-          "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
-          "name": "verbose",
-          "summary": "Show generated data in the test results output.",
-          "allowNo": false,
-          "type": "boolean"
-        }
-      },
-      "hasDynamicHelp": true,
-      "hiddenAliases": [],
-      "id": "agent:test:run",
-      "pluginAlias": "@salesforce/plugin-agent",
-      "pluginName": "@salesforce/plugin-agent",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Start an agent test in your org.",
-      "enableJsonFlag": true,
-      "envVariablesSection": {
-        "header": "ENVIRONMENT VARIABLES",
-        "body": [
-          {
-            "name": "SF_TARGET_ORG",
-            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
-          }
-        ]
-      },
-      "errorCodes": {
-        "header": "ERROR CODES",
-        "body": [
-          {
-            "name": "Succeeded (0)",
-            "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
-          },
-          {
-            "name": "Failed (1)",
-            "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
-          },
-          {
-            "name": "NotFound (2)",
-            "description": "Test definition not found or invalid test name."
-          },
-          {
-            "name": "OperationFailed (4)",
-            "description": "Failed to start or poll test due to API or network errors."
-          }
-        ]
-      },
-      "isESM": true,
-      "relativePath": [
-        "lib",
-        "commands",
-        "agent",
-        "test",
-        "run.js"
-      ],
-      "aliasPermutations": [],
-      "permutations": [
-        "agent:test:run",
-        "test:agent:run",
-        "test:run:agent",
-        "agent:run:test",
-        "run:agent:test",
-        "run:test:agent"
-      ]
-    },
-    "agent:preview:end": {
-      "aliases": [],
-      "args": {},
-      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to end it. This command also displays the local directory where the session trace files are stored.\n\nThe 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 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 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.",
-      "examples": [
-        "End a preview session of a published agent by specifying its session ID and API name ; use the default org:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --api-name My_Published_Agent",
-        "Similar to previous example, but don't specify a session ID; you get an error if the published agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent --target-org my-dev-org",
-        "End a preview session of an agent using its authoring bundle API name; you get an error if the agent has more than one active session.\n<%= config.bin %> <%= command.id %> --authoring-bundle My_Local_Agent"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "flags-dir": {
-          "helpGroup": "GLOBAL",
-          "name": "flags-dir",
-          "summary": "Import flag values from a directory.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "target-org": {
-          "char": "o",
-          "name": "target-org",
-          "noCacheDefault": true,
-          "required": true,
-          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
-          "hasDynamicHelp": true,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-version": {
-          "description": "Override the api version used for api requests made by this command",
-          "name": "api-version",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "session-id": {
-          "name": "session-id",
-          "required": false,
-          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see the list of all sessions.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+          "name": "test-runner",
+          "summary": "Explicitly specify which test runner to use (agentforce-studio or testing-center).",
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "agentforce-studio",
+            "testing-center"
+          ],
           "type": "option"
+        },
+        "verbose": {
+          "description": "When enabled, includes detailed generated data (such as invoked actions) in the human-readable test results output. This is useful for debugging test failures and understanding what actions were actually invoked during the test run.\n\nThe generated data is in JSON format and includes the Apex classes or Flows that were invoked, the Salesforce objects that were touched, and so on. Use the JSON structure of this information to build the test case JSONPath expression when using custom evaluations.",
+          "name": "verbose",
+          "summary": "Show generated data in the test results output.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:preview:end",
+      "id": "agent:test:run",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "End an existing programmatic agent preview session and get trace location.",
+      "summary": "Start an agent test in your org.",
       "enableJsonFlag": true,
-      "requiresProject": true,
       "envVariablesSection": {
         "header": "ENVIRONMENT VARIABLES",
         "body": [
@@ -1929,19 +2272,19 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Preview session ended successfully and traces saved."
+            "description": "Test started successfully (without --wait), or test completed successfully (with --wait)."
           },
           {
-            "name": "NotFound (2)",
-            "description": "Agent not found, or no preview session exists for this agent."
+            "name": "Failed (1)",
+            "description": "Tests encountered execution errors (test cases with ERROR status when using --wait)."
           },
           {
-            "name": "PreviewEndFailed (4)",
-            "description": "Failed to end the preview session."
+            "name": "NotFound (2)",
+            "description": "Test definition not found or invalid test name."
           },
           {
-            "name": "SessionAmbiguous (5)",
-            "description": "Multiple preview sessions found; specify --session-id to choose one."
+            "name": "OperationFailed (4)",
+            "description": "Failed to start or poll test due to API or network errors."
           }
         ]
       },
@@ -1950,27 +2293,30 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "end.js"
+        "test",
+        "run.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:end",
-        "preview:agent:end",
-        "preview:end:agent",
-        "agent:end:preview",
-        "end:agent:preview",
-        "end:preview:agent"
+        "agent:test:run",
+        "test:agent:run",
+        "test:run:agent",
+        "agent:run:test",
+        "run:agent:test",
+        "run:test:agent"
       ]
     },
-    "agent:preview:send": {
+    "agent:trace:delete": {
       "aliases": [],
       "args": {},
-      "description": "You must have previously started a programmatic agent preview session with the \"agent preview start\" command to then use this command to send the agent a message (utterance). This command then displays the agent's response.\n\nThe 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 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 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.",
+      "description": "Deletes trace files recorded during agent preview sessions. By default, shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, deletes all traces for all agents and sessions. Use flags to narrow the scope: filter by agent name (--agent), by session (--session-id), or by age (--older-than).",
       "examples": [
-        "Send a message to an activated published agent using its API name and session ID; use the default org:\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --session-id <SESSION_ID>",
-        "Similar to previous example, but don't specify a session ID; you get an error if the agent has more than one active session. Use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --utterance \"What can you help me with?\" --api-name My_Published_Agent --target-org my-dev-org",
-        "Send a message to an agent using its authoring bundle API name; you get an error if the agent has more than one active session:\n<%= config.bin %> <%= command.id %> --utterance \"what can you help me with?\" --authoring-bundle My_Local_Agent"
+        "Delete all traces for all agents and sessions (with confirmation prompt):\n<%= config.bin %> <%= command.id %>",
+        "Delete all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
+        "Delete traces from a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
+        "Delete traces older than 7 days:\n<%= config.bin %> <%= command.id %> --older-than 7d",
+        "Delete traces older than 24 hours for a specific agent, no prompt:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
+        "Delete all traces without confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
       ],
       "flags": {
         "json": {
@@ -1988,93 +2334,51 @@
           "multiple": false,
           "type": "option"
         },
-        "target-org": {
-          "char": "o",
-          "name": "target-org",
-          "noCacheDefault": true,
-          "required": true,
-          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
-          "hasDynamicHelp": true,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-version": {
-          "description": "Override the api version used for api requests made by this command",
-          "name": "api-version",
+        "agent": {
+          "char": "a",
+          "name": "agent",
+          "summary": "Only delete traces for this agent name (substring match). Matches against the name used when starting the session, whether that's an authoring bundle or a published agent API name.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "session-id": {
           "name": "session-id",
-          "required": false,
-          "summary": "Session ID outputted by \"agent preview start\". Not required when the agent has exactly one active session. Run \"agent preview sessions\" to see list of all sessions.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "utterance": {
-          "char": "u",
-          "name": "utterance",
-          "required": true,
-          "summary": "Utterance to send to the agent, enclosed in double quotes.",
+          "summary": "Only delete traces from this session ID.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
+        "older-than": {
+          "name": "older-than",
+          "summary": "Only delete traces older than this duration. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks (e.g. 7d, 24h, 2w).",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "no-prompt": {
+          "name": "no-prompt",
+          "summary": "Skip the confirmation prompt and delete immediately.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:preview:send",
+      "id": "agent:trace:delete",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Send a message to an existing agent preview session.",
+      "summary": "Delete agent preview trace files.",
       "enableJsonFlag": true,
       "requiresProject": true,
-      "envVariablesSection": {
-        "header": "ENVIRONMENT VARIABLES",
-        "body": [
-          {
-            "name": "SF_TARGET_ORG",
-            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
-          }
-        ]
-      },
       "errorCodes": {
         "header": "ERROR CODES",
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Message sent successfully and agent response received."
-          },
-          {
-            "name": "NotFound (2)",
-            "description": "Agent not found, or no preview session exists for this agent."
-          },
-          {
-            "name": "PreviewSendFailed (4)",
-            "description": "Failed to send message or receive response from the preview session."
-          },
-          {
-            "name": "SessionAmbiguous (5)",
-            "description": "Multiple preview sessions found; specify --session-id to choose one."
+            "description": "Traces deleted successfully (or no traces matched)."
           }
         ]
       },
@@ -2083,25 +2387,31 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "send.js"
+        "trace",
+        "delete.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:send",
-        "preview:agent:send",
-        "preview:send:agent",
-        "agent:send:preview",
-        "send:agent:preview",
-        "send:preview:agent"
+        "agent:trace:delete",
+        "trace:agent:delete",
+        "trace:delete:agent",
+        "agent:delete:trace",
+        "delete:agent:trace",
+        "delete:trace:agent"
       ]
     },
-    "agent:preview:sessions": {
+    "agent:trace:list": {
       "aliases": [],
       "args": {},
-      "description": "This command lists the agent preview sessions that were started with the \"agent preview start\" command and are still in the local cache. Use this command to discover specific session IDs that you can pass to the \"agent preview send\" or \"agent preview end\" commands with the --session-id flag.\n\nProgrammatic agent preview sessions can be started for both published activated agents and by using an agent's local authoring bundle, which contains its Agent Script file. In this command's output table, the Agent column contains either the API name of the authoring bundle or the published agent, whichever was used when starting the session. In the table, if the same API name has multiple rows with different session IDs, then it means that you previously started multiple preview sessions with the associated agent.",
+      "description": "Lists trace files recorded during agent preview sessions. By default, lists all traces for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).\n\nEach row in the output corresponds to one trace file, which in turn corresponds to one agent session. The Agent column shows the authoring bundle or API name used when starting the session.",
       "examples": [
-        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
+        "List all traces for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
+        "List all traces for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
+        "List traces for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
+        "List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
+        "List traces recorded on or after a specific UTC time:\n<%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z",
+        "Filter by agent and date together:\n<%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20",
+        "Return results as JSON:\n<%= config.bin %> <%= command.id %> --json"
       ],
       "flags": {
         "json": {
@@ -2118,16 +2428,39 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "session-id": {
+          "name": "session-id",
+          "summary": "Session ID used to filter the list of trace files.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "agent": {
+          "char": "a",
+          "name": "agent",
+          "summary": "Only show traces for this agent name (substring match). Matches against the name used when starting the session, whether that's an authoring bundle or a published agent API name.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "since": {
+          "description": "Accepts ISO 8601 format: date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or date-time with milliseconds (2026-04-20T14:00:00.000Z). The \"Recorded At\" values shown in the table output are valid inputs.",
+          "name": "since",
+          "summary": "Date used to filter the list of trace files; only those recorded on or after the date are listed.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:preview:sessions",
+      "id": "agent:trace:list",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "List all known programmatic agent preview sessions.",
+      "summary": "List the trace files that were recorded during all agent preview sessions.",
       "enableJsonFlag": true,
       "requiresProject": true,
       "errorCodes": {
@@ -2135,7 +2468,7 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Sessions listed successfully (or empty list if no active sessions)."
+            "description": "Trace files listed successfully (or empty list if none found)."
           }
         ]
       },
@@ -2144,27 +2477,31 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "sessions.js"
+        "trace",
+        "list.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:sessions",
-        "preview:agent:sessions",
-        "preview:sessions:agent",
-        "agent:sessions:preview",
-        "sessions:agent:preview",
-        "sessions:preview:agent"
+        "agent:trace:list",
+        "trace:agent:list",
+        "trace:list:agent",
+        "agent:list:trace",
+        "list:agent:trace",
+        "list:trace:agent"
       ]
     },
-    "agent:preview:start": {
+    "agent:trace:read": {
       "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 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.",
+      "description": "Reads trace files recorded during an agent preview session and outputs them in one of three formats.\n\n**--format summary** (default): A per-turn narrative showing topic routing, actions executed, and the agent's response. Use this to quickly understand what happened in a session.\n\n**--format detail**: Diagnostic drill-down into a specific dimension (--dimension required). Filters output to only the trace steps relevant to that dimension, minimizing noise.\n\n**--format raw**: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nAvailable dimensions for --format detail: actions, grounding, routing, errors.\n\nUse --turn N to scope output to a single conversation turn.",
       "examples": [
-        "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 (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
+        "Show a session summary (all turns):\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
+        "Show summary for a single turn:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2",
+        "Drill into action execution across all turns:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions",
+        "Drill into routing decisions for a specific turn:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1",
+        "Show all errors across the session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors",
+        "Output raw trace JSON for custom parsing:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw",
+        "Return results as JSON:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json"
       ],
       "flags": {
         "json": {
@@ -2182,128 +2519,78 @@
           "multiple": false,
           "type": "option"
         },
-        "target-org": {
-          "char": "o",
-          "name": "target-org",
-          "noCacheDefault": true,
+        "session-id": {
+          "char": "s",
+          "name": "session-id",
           "required": true,
-          "summary": "Username or alias of the target org. Not required if the `target-org` configuration variable is already set.",
-          "hasDynamicHelp": true,
-          "multiple": false,
-          "type": "option"
-        },
-        "api-version": {
-          "description": "Override the api version used for api requests made by this command",
-          "name": "api-version",
+          "summary": "Session ID to read traces for.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "api-name": {
-          "char": "n",
-          "name": "api-name",
-          "summary": "API name of the activated published agent you want to preview.",
+        "format": {
+          "char": "f",
+          "name": "format",
+          "summary": "Output format: summary (default), detail, or raw. Use detail with --dimension to drill into a specific aspect of the trace.",
+          "default": "summary",
           "hasDynamicHelp": false,
           "multiple": false,
+          "options": [
+            "summary",
+            "detail",
+            "raw"
+          ],
           "type": "option"
         },
-        "authoring-bundle": {
-          "name": "authoring-bundle",
-          "summary": "API name of the authoring bundle metadata component that contains the agent's Agent Script file.",
+        "dimension": {
+          "char": "d",
+          "name": "dimension",
+          "summary": "Dimension to drill into when using --format detail. One of: actions, grounding, routing, errors. Required when --format is detail.",
           "hasDynamicHelp": false,
           "multiple": false,
-          "type": "option"
-        },
-        "use-live-actions": {
-          "exclusive": [
-            "simulate-actions"
-          ],
-          "name": "use-live-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"
+          "options": [
+            "actions",
+            "grounding",
+            "routing",
+            "errors"
           ],
-          "name": "simulate-actions",
-          "summary": "Use AI to simulate action execution instead of calling real actions. Required with --authoring-bundle.",
-          "allowNo": false,
-          "type": "boolean"
+          "type": "option"
         },
-        "agent-json": {
-          "dependsOn": [
-            "authoring-bundle"
-          ],
-          "hidden": true,
-          "name": "agent-json",
-          "summary": "Path to a pre-compiled AgentJSON file to use instead of compiling the Agent Script file. Intended for internal use and testing.",
+        "turn": {
+          "char": "t",
+          "name": "turn",
+          "summary": "Scope output to this conversation turn number.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         }
       },
-      "hasDynamicHelp": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:preview:start",
+      "id": "agent:trace:read",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Start a programmatic agent preview session.",
+      "summary": "Read and analyze trace files from an agent preview session.",
       "enableJsonFlag": true,
       "requiresProject": true,
-      "envVariablesSection": {
-        "header": "ENVIRONMENT VARIABLES",
-        "body": [
-          {
-            "name": "SF_TARGET_ORG",
-            "description": "Username or alias of your default org. Overrides the target-org configuration variable."
-          }
-        ]
-      },
-      "errorCodes": {
-        "header": "ERROR CODES",
-        "body": [
-          {
-            "name": "Succeeded (0)",
-            "description": "Preview session started successfully."
-          },
-          {
-            "name": "Failed (1)",
-            "description": "Agent Script compilation failed (syntax errors in the script)."
-          },
-          {
-            "name": "NotFound (2)",
-            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
-          },
-          {
-            "name": "ServerError (3)",
-            "description": "Compilation API returned HTTP 500 (server error during compilation)."
-          },
-          {
-            "name": "PreviewStartFailed (4)",
-            "description": "Preview session failed to start due to API or network errors."
-          }
-        ]
-      },
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "agent",
-        "preview",
-        "start.js"
+        "trace",
+        "read.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:start",
-        "preview:agent:start",
-        "preview:start:agent",
-        "agent:start:preview",
-        "start:agent:preview",
-        "start:preview:agent"
+        "agent:trace:read",
+        "trace:agent:read",
+        "trace:read:agent",
+        "agent:read:trace",
+        "read:agent:trace",
+        "read:trace:agent"
       ]
     },
     "agent:validate:authoring-bundle": {
@@ -2421,5 +2708,5 @@
       ]
     }
   },
-  "version": "1.37.0"
+  "version": "1.38.0"
 }