@salesforce/plugin-agent 1.42.0 → 1.42.1

package/oclif.manifest.json

@@ -745,6 +745,18 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "source-type": {
+          "name": "source-type",
+          "summary": "Filter by source type: sfdrive, knowledge, or retriever.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "sfdrive",
+            "knowledge",
+            "retriever"
+          ],
+          "type": "option"
         }
       },
       "hasDynamicHelp": true,
@@ -932,6 +944,13 @@
           "summary": "Restrict to public Knowledge articles only (KNOWLEDGE libraries, triggers re-indexing).",
           "allowNo": true,
           "type": "boolean"
+        },
+        "retriever-id": {
+          "name": "retriever-id",
+          "summary": "Swap the retriever for a RETRIEVER library (must be an active Custom Retriever ID).",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": true,
@@ -1018,7 +1037,7 @@
           "required": true,
           "summary": "Path to the file to upload.",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
           "type": "option"
         },
         "wait": {
@@ -2502,13 +2521,16 @@
         "run:test:agent"
       ]
     },
-    "agent:validate:authoring-bundle": {
+    "agent:preview:end": {
       "aliases": [],
       "args": {},
-      "description": "An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension \".agent\") that fully describes the agent using the Agent Script language.\n\nThis command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you code the Agent Script file to ensure that it's valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred.\n\nThis command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.",
+      "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, respectively. 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\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
       "examples": [
-        "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
-        "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
+        "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",
+        "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
+        "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_org>"
       ],
       "flags": {
         "json": {
@@ -2543,23 +2565,63 @@
           "multiple": false,
           "type": "option"
         },
+        "session-id": {
+          "exclusive": [
+            "all"
+          ],
+          "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",
+          "exclusive": [
+            "authoring-bundle"
+          ],
           "name": "api-name",
-          "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
+          "summary": "API name of the activated published agent you want to preview.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "authoring-bundle": {
+          "exclusive": [
+            "api-name"
+          ],
+          "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"
+        },
+        "all": {
+          "exclusive": [
+            "session-id"
+          ],
+          "name": "all",
+          "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "no-prompt": {
+          "char": "p",
+          "name": "no-prompt",
+          "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:validate:authoring-bundle",
+      "id": "agent:preview:end",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
+      "summary": "End an existing programmatic agent preview session and get trace location.",
       "enableJsonFlag": true,
       "requiresProject": true,
       "envVariablesSection": {
@@ -2576,57 +2638,56 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Agent Script file compiled successfully without errors."
+            "description": "Preview session ended successfully and traces saved."
           },
           {
-            "name": "Failed (1)",
-            "description": "Compilation errors found in the Agent Script file."
+            "name": "ExactlyOneRequired (2)",
+            "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
           },
           {
             "name": "NotFound (2)",
-            "description": "Validation/compilation API returned HTTP 404. The API endpoint may not be available in your org or region."
+            "description": "Agent not found, or no preview session exists for this agent."
           },
           {
-            "name": "ServerError (3)",
-            "description": "Validation/compilation API returned HTTP 500. A server error occurred during compilation."
+            "name": "PreviewEndFailed (4)",
+            "description": "Failed to end the preview session."
+          },
+          {
+            "name": "PreviewEndPartialFailure (68)",
+            "description": "With --all, one or more sessions failed to end while others succeeded."
+          },
+          {
+            "name": "SessionAmbiguous (5)",
+            "description": "Multiple preview sessions found; specify --session-id to choose one."
           }
         ]
       },
-      "FLAGGABLE_PROMPTS": {
-        "api-name": {
-          "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
-          "promptMessage": "API name of the authoring bundle to validate"
-        }
-      },
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "agent",
-        "validate",
-        "authoring-bundle.js"
+        "preview",
+        "end.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:validate:authoring-bundle",
-        "validate:agent:authoring-bundle",
-        "validate:authoring-bundle:agent",
-        "agent:authoring-bundle:validate",
-        "authoring-bundle:agent:validate",
-        "authoring-bundle:validate:agent"
+        "agent:preview:end",
+        "preview:agent:end",
+        "preview:end:agent",
+        "agent:end:preview",
+        "end:agent:preview",
+        "end:preview:agent"
       ]
     },
-    "agent:trace:delete": {
+    "agent:preview:send": {
       "aliases": [],
       "args": {},
-      "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API name (--agent), by session (--session-id), or by age (--older-than).",
+      "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": [
-        "Delete all traces for all agents and sessions; prompt for confirmation:\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; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
-        "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
+        "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": {
@@ -2644,51 +2705,93 @@
           "multiple": false,
           "type": "option"
         },
-        "agent": {
-          "char": "a",
-          "name": "agent",
-          "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
+        "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",
-          "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
+          "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"
         },
-        "older-than": {
-          "name": "older-than",
-          "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
+        "utterance": {
+          "char": "u",
+          "name": "utterance",
+          "required": true,
+          "summary": "Utterance to send to the agent, enclosed in double quotes.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "no-prompt": {
-          "name": "no-prompt",
-          "summary": "Skip the confirmation prompt and delete immediately.",
-          "allowNo": false,
-          "type": "boolean"
+        "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": false,
+      "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:trace:delete",
+      "id": "agent:preview:send",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Delete trace files from an agent preview session.",
+      "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": "Traces deleted successfully (or no traces matched)."
+            "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."
           }
         ]
       },
@@ -2697,31 +2800,25 @@
         "lib",
         "commands",
         "agent",
-        "trace",
-        "delete.js"
+        "preview",
+        "send.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:trace:delete",
-        "trace:agent:delete",
-        "trace:delete:agent",
-        "agent:delete:trace",
-        "delete:agent:trace",
-        "delete:trace:agent"
+        "agent:preview:send",
+        "preview:agent:send",
+        "preview:send:agent",
+        "agent:send:preview",
+        "send:agent:preview",
+        "send:preview:agent"
       ]
     },
-    "agent:trace:list": {
+    "agent:preview:sessions": {
       "aliases": [],
       "args": {},
-      "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files 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.",
+      "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 trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
-        "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
-        "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
-        "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
-        "List trace files 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"
+        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
       ],
       "flags": {
         "json": {
@@ -2738,39 +2835,16 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
-        },
-        "session-id": {
-          "name": "session-id",
-          "summary": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "agent": {
-          "char": "a",
-          "name": "agent",
-          "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either 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:trace:list",
+      "id": "agent:preview:sessions",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "List the available trace files that were recorded during all agent preview sessions.",
+      "summary": "List all known programmatic agent preview sessions.",
       "enableJsonFlag": true,
       "requiresProject": true,
       "errorCodes": {
@@ -2778,7 +2852,7 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Trace files listed successfully (or empty list if none found)."
+            "description": "Sessions listed successfully (or empty list if no active sessions)."
           }
         ]
       },
@@ -2787,132 +2861,27 @@
         "lib",
         "commands",
         "agent",
-        "trace",
-        "list.js"
-      ],
-      "aliasPermutations": [],
-      "permutations": [
-        "agent:trace:list",
-        "trace:agent:list",
-        "trace:list:agent",
-        "agent:list:trace",
-        "list:agent:trace",
-        "list:trace:agent"
-      ]
-    },
-    "agent:trace:read": {
-      "aliases": [],
-      "args": {},
-      "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- 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 preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
-      "examples": [
-        "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
-        "Show a trace summary for the second turn (utterance or response) of the conversation:\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 the first turn of the conversation:\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": {
-          "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"
-        },
-        "session-id": {
-          "char": "s",
-          "name": "session-id",
-          "required": true,
-          "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "format": {
-          "char": "f",
-          "name": "format",
-          "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
-          "default": "summary",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "summary",
-            "detail",
-            "raw"
-          ],
-          "type": "option"
-        },
-        "dimension": {
-          "char": "d",
-          "name": "dimension",
-          "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "options": [
-            "actions",
-            "grounding",
-            "routing",
-            "errors"
-          ],
-          "type": "option"
-        },
-        "turn": {
-          "char": "t",
-          "name": "turn",
-          "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "agent:trace:read",
-      "pluginAlias": "@salesforce/plugin-agent",
-      "pluginName": "@salesforce/plugin-agent",
-      "pluginType": "core",
-      "strict": true,
-      "summary": "Read trace files from an agent preview session.",
-      "enableJsonFlag": true,
-      "requiresProject": true,
-      "isESM": true,
-      "relativePath": [
-        "lib",
-        "commands",
-        "agent",
-        "trace",
-        "read.js"
+        "preview",
+        "sessions.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:trace:read",
-        "trace:agent:read",
-        "trace:read:agent",
-        "agent:read:trace",
-        "read:agent:trace",
-        "read:trace:agent"
+        "agent:preview:sessions",
+        "preview:agent:sessions",
+        "preview:sessions:agent",
+        "agent:sessions:preview",
+        "sessions:agent:preview",
+        "sessions:preview:agent"
       ]
     },
-    "agent:preview:end": {
+    "agent:preview:start": {
       "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, respectively. 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\nUse the --all flag to end all active preview sessions at once. You can combine --all with --api-name or --authoring-bundle to end only sessions for a specific agent, or use --all on its own to end every session across all agents in the project.",
+      "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": [
-        "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",
-        "End all active preview sessions for a specific agent without prompting:\n<%= config.bin %> <%= command.id %> --all --authoring-bundle My_Local_Agent --target-org <target_org> --no-prompt",
-        "End all active preview sessions across every agent in the local session cache for an org:\n<%= config.bin %> <%= command.id %> --all --target-org <target_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 (always uses live actions):\n<%= config.bin %> <%= command.id %> --api-name My_Published_Agent"
       ],
       "flags": {
         "json": {
@@ -2947,22 +2916,8 @@
           "multiple": false,
           "type": "option"
         },
-        "session-id": {
-          "exclusive": [
-            "all"
-          ],
-          "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",
-          "exclusive": [
-            "authoring-bundle"
-          ],
           "name": "api-name",
           "summary": "API name of the activated published agent you want to preview.",
           "hasDynamicHelp": false,
@@ -2970,40 +2925,50 @@
           "type": "option"
         },
         "authoring-bundle": {
-          "exclusive": [
-            "api-name"
-          ],
           "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"
         },
-        "all": {
+        "use-live-actions": {
           "exclusive": [
-            "session-id"
+            "simulate-actions"
           ],
-          "name": "all",
-          "summary": "End all active preview sessions. Combine with --api-name or --authoring-bundle to limit to a specific agent, or use with only --target-org to end sessions for all agents found in the local session cache. Requires --target-org.",
+          "name": "use-live-actions",
+          "summary": "Execute real actions in the org (Apex classes, flows, etc.). Required with --authoring-bundle.",
           "allowNo": false,
           "type": "boolean"
         },
-        "no-prompt": {
-          "char": "p",
-          "name": "no-prompt",
-          "summary": "Don't prompt for confirmation before ending sessions. Has an effect only when used with --all.",
+        "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:end",
+      "id": "agent:preview:start",
       "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 a programmatic agent preview session.",
       "enableJsonFlag": true,
       "requiresProject": true,
       "envVariablesSection": {
@@ -3020,27 +2985,23 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Preview session ended successfully and traces saved."
+            "description": "Preview session started successfully."
           },
           {
-            "name": "ExactlyOneRequired (2)",
-            "description": "Neither --api-name nor --authoring-bundle was provided (required when --all is not set)."
+            "name": "Failed (1)",
+            "description": "Agent Script compilation failed (syntax errors in the script)."
           },
           {
             "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."
+            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
           },
           {
-            "name": "PreviewEndPartialFailure (68)",
-            "description": "With --all, one or more sessions failed to end while others succeeded."
+            "name": "ServerError (3)",
+            "description": "Compilation API returned HTTP 500 (server error during compilation)."
           },
           {
-            "name": "SessionAmbiguous (5)",
-            "description": "Multiple preview sessions found; specify --session-id to choose one."
+            "name": "PreviewStartFailed (4)",
+            "description": "Preview session failed to start due to API or network errors."
           }
         ]
       },
@@ -3050,26 +3011,29 @@
         "commands",
         "agent",
         "preview",
-        "end.js"
+        "start.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:end",
-        "preview:agent:end",
-        "preview:end:agent",
-        "agent:end:preview",
-        "end:agent:preview",
-        "end:preview:agent"
+        "agent:preview:start",
+        "preview:agent:start",
+        "preview:start:agent",
+        "agent:start:preview",
+        "start:agent:preview",
+        "start:preview: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": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Use this command to delete some or all of the trace files.\n\nBy default, this command shows a preview of what will be deleted and prompts for confirmation. Use --no-prompt to skip confirmation.\n\nWithout filters, this comamnd deletes all trace files for all agents and sessions. Use flags to narrow the scope: filter by agent API 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; prompt for confirmation:\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; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt",
+        "Delete all traces for all agents and sessions; don't prompt for confirmation:\n<%= config.bin %> <%= command.id %> --no-prompt"
       ],
       "flags": {
         "json": {
@@ -3087,93 +3051,141 @@
           "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,
+        "agent": {
+          "char": "a",
+          "name": "agent",
+          "summary": "API name of the agent used to filter the list of trace files you want to delete. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "session-id": {
+          "name": "session-id",
+          "summary": "Session ID used to filter the list of trace files you want to delete. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "older-than": {
+          "name": "older-than",
+          "summary": "Duration used to filter the list of trace files; only files older than the duration are deleted. Accepts a number followed by a unit: m/minutes, h/hours, d/days, w/weeks. Examples: 7d, 24h, 2w.",
+          "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "api-version": {
-          "description": "Override the api version used for api requests made by this command",
-          "name": "api-version",
+        "no-prompt": {
+          "name": "no-prompt",
+          "summary": "Skip the confirmation prompt and delete immediately.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "agent:trace:delete",
+      "pluginAlias": "@salesforce/plugin-agent",
+      "pluginName": "@salesforce/plugin-agent",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Delete trace files from an agent preview session.",
+      "enableJsonFlag": true,
+      "requiresProject": true,
+      "errorCodes": {
+        "header": "ERROR CODES",
+        "body": [
+          {
+            "name": "Succeeded (0)",
+            "description": "Traces deleted successfully (or no traces matched)."
+          }
+        ]
+      },
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "agent",
+        "trace",
+        "delete.js"
+      ],
+      "aliasPermutations": [],
+      "permutations": [
+        "agent:trace:delete",
+        "trace:agent:delete",
+        "trace:delete:agent",
+        "agent:delete:trace",
+        "delete:agent:trace",
+        "delete:trace:agent"
+      ]
+    },
+    "agent:trace:list": {
+      "aliases": [],
+      "args": {},
+      "description": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. By default, this command lists all trace files 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 trace files for all agents and sessions:\n<%= config.bin %> <%= command.id %>",
+        "List all trace files for a specific agent:\n<%= config.bin %> <%= command.id %> --agent My_Agent",
+        "List trace files for a specific session:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
+        "List trace files recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):\n<%= config.bin %> <%= command.id %> --since 2026-04-20",
+        "List trace files 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": {
+          "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"
         },
         "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": "Session ID used to filter the list of trace files. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs.",
           "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.",
+        "agent": {
+          "char": "a",
+          "name": "agent",
+          "summary": "API name of the agent used to filter the list of available trace files. Matches against the API name used when starting the session, either an authoring bundle or a published agent API name.",
           "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.",
+        "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": true,
+      "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:preview:send",
+      "id": "agent:trace:list",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Send a message to an existing agent preview session.",
+      "summary": "List the available trace files that were recorded during all agent preview sessions.",
       "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": "Trace files listed successfully (or empty list if none found)."
           }
         ]
       },
@@ -3182,25 +3194,31 @@
         "lib",
         "commands",
         "agent",
-        "preview",
-        "send.js"
+        "trace",
+        "list.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:send",
-        "preview:agent:send",
-        "preview:send:agent",
-        "agent:send:preview",
-        "send:agent:preview",
-        "send:preview:agent"
+        "agent:trace:list",
+        "trace:agent:list",
+        "trace:list:agent",
+        "agent:list:trace",
+        "list:agent:trace",
+        "list:trace:agent"
       ]
     },
-    "agent:preview:sessions": {
+    "agent:trace:read": {
       "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": "When you run an agent preview conversation (either interactive or programmatic), trace files are automatically recorded and saved in your local DX project. Each turn (utterance or response) of a conversation creates trace data. Use this command to view trace data for a specific preview session, so you can then analyze the trace data to observe, monitor, investigate, and troubleshoot agent events and behavior.\n\nUse the --format flag to specify one of these formats of the outputted trace data:\n\n- 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 preview session.\n- detail: Diagnostic drill-down into a specific dimension. Filters output to only the trace steps relevant to that dimension, minimizing noise.\n- raw: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.\n\nIf you specify \"--format detail\", you must also specify a dimension with the --dimension flag. Dimensions are a way to slice and analyze the agent execution trace from a specific angle or concern. Instead of looking at the raw sequence of everything that happened, each dimension filters and organizes the trace data to answer a specific type of question. These are the available dimensions and the information they provide:\n\n- actions: The actions the agent executed. Includes action name, input parameters, output, and latency. Use this dimension to understand what the agent actually did when answering an utterance in the preview session.\n- grounding: The reasoning steps used by the LLM. Use this dimension to see how the agent \"thought\" about the problem - the AI reasoning that determined which actions to take.\n- routing: How the agent navigated between subagents. Use this dimension to understand conversation flow - when and why the agent switched between different subagents or contexts during the conversation.\n- errors: Aggregates all errors during the session. Use this dimension to quickly identify and debug issues across all steps.",
       "examples": [
-        "List all cached agent preview sessions:\n<%= config.bin %> <%= command.id %>"
+        "Show a session trace summary for all turns in the session with the specified ID:\n<%= config.bin %> <%= command.id %> --session-id <SESSION_ID>",
+        "Show a trace summary for the second turn (utterance or response) of the conversation:\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 the first turn of the conversation:\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": {
@@ -3217,53 +3235,88 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "session-id": {
+          "char": "s",
+          "name": "session-id",
+          "required": true,
+          "summary": "Session ID to read traces for. Use the \"agent preview sessions\" CLI command to list all known agent preview sessions along with their session IDs",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "format": {
+          "char": "f",
+          "name": "format",
+          "summary": "Output format of the trace data; specifies the level of detail you want in the trace files.",
+          "default": "summary",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "summary",
+            "detail",
+            "raw"
+          ],
+          "type": "option"
+        },
+        "dimension": {
+          "char": "d",
+          "name": "dimension",
+          "summary": "Dimension to drill into when using \"--format detail\"; used to filter and organize the trace data to answer a specific type of question.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "actions",
+            "grounding",
+            "routing",
+            "errors"
+          ],
+          "type": "option"
+        },
+        "turn": {
+          "char": "t",
+          "name": "turn",
+          "summary": "Turn number for which you want trace data. A turn is a single utterance or response in a conversation, starting with 1.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "agent:preview:sessions",
+      "id": "agent:trace:read",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "List all known programmatic agent preview sessions.",
+      "summary": "Read trace files from an agent preview session.",
       "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"
+        "trace",
+        "read.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:sessions",
-        "preview:agent:sessions",
-        "preview:sessions:agent",
-        "agent:sessions:preview",
-        "sessions:agent:preview",
-        "sessions:preview:agent"
+        "agent:trace:read",
+        "trace:agent:read",
+        "trace:read:agent",
+        "agent:read:trace",
+        "read:agent:trace",
+        "read:trace:agent"
       ]
     },
-    "agent:preview:start": {
+    "agent:validate:authoring-bundle": {
       "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": "An authoring bundle is a metadata type (named aiAuthoringBundle) that provides the blueprint for an agent. The metadata type contains two files: the standard metatada XML file and an Agent Script file (extension \".agent\") that fully describes the agent using the Agent Script language.\n\nThis command validates that the Agent Script file in the authoring bundle compiles without errors so that you can later publish the bundle to your org. Use this command while you code the Agent Script file to ensure that it's valid. If the validation fails, the command outputs the list of syntax errors, a brief description of the error, and the location in the Agent Script file where the error occurred.\n\nThis command uses the API name of the authoring bundle. If you don't provide an API name with the --api-name flag, the command searches the current DX project and outputs a list of authoring bundles that it found for you to choose from.",
       "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"
+        "Validate an authoring bundle by being prompted for its API name; use your default org:\n<%= config.bin %> <%= command.id %>",
+        "Validate an authoring bundle with API name MyAuthoringBundle; use the org with alias \"my-dev-org\":\n<%= config.bin %> <%= command.id %> --api-name MyAuthoringBundle --target-org my-dev-org"
       ],
       "flags": {
         "json": {
@@ -3301,43 +3354,7 @@
         "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.",
+          "summary": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -3345,12 +3362,12 @@
       },
       "hasDynamicHelp": true,
       "hiddenAliases": [],
-      "id": "agent:preview:start",
+      "id": "agent:validate:authoring-bundle",
       "pluginAlias": "@salesforce/plugin-agent",
       "pluginName": "@salesforce/plugin-agent",
       "pluginType": "core",
       "strict": true,
-      "summary": "Start a programmatic agent preview session.",
+      "summary": "Validate an authoring bundle to ensure its Agent Script file compiles successfully and can be used to publish an agent.",
       "enableJsonFlag": true,
       "requiresProject": true,
       "envVariablesSection": {
@@ -3367,42 +3384,44 @@
         "body": [
           {
             "name": "Succeeded (0)",
-            "description": "Preview session started successfully."
+            "description": "Agent Script file compiled successfully without errors."
           },
           {
             "name": "Failed (1)",
-            "description": "Agent Script compilation failed (syntax errors in the script)."
+            "description": "Compilation errors found in the Agent Script file."
           },
           {
             "name": "NotFound (2)",
-            "description": "Agent not found, or compilation API returned HTTP 404 (endpoint may not be available in your org or region)."
+            "description": "Validation/compilation API returned HTTP 404. The API 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."
+            "description": "Validation/compilation API returned HTTP 500. A server error occurred during compilation."
           }
         ]
       },
+      "FLAGGABLE_PROMPTS": {
+        "api-name": {
+          "message": "API name of the authoring bundle you want to validate; if not specified, the command provides a list that you can choose from.",
+          "promptMessage": "API name of the authoring bundle to validate"
+        }
+      },
       "isESM": true,
       "relativePath": [
         "lib",
         "commands",
         "agent",
-        "preview",
-        "start.js"
+        "validate",
+        "authoring-bundle.js"
       ],
       "aliasPermutations": [],
       "permutations": [
-        "agent:preview:start",
-        "preview:agent:start",
-        "preview:start:agent",
-        "agent:start:preview",
-        "start:agent:preview",
-        "start:preview:agent"
+        "agent:validate:authoring-bundle",
+        "validate:agent:authoring-bundle",
+        "validate:authoring-bundle:agent",
+        "agent:authoring-bundle:validate",
+        "authoring-bundle:agent:validate",
+        "authoring-bundle:validate:agent"
       ]
     },
     "agent:adl:file:add": {
@@ -3410,7 +3429,8 @@
       "args": {},
       "description": "Adds one or more files to an existing SFDRIVE data library and triggers SearchIndex re-hydration. This is the day-2 operation for adding files to an already-provisioned library.\n\nConstraints: at least 1 file required, no duplicate file names in a batch, maximum 1000 files per library.",
       "examples": [
-        "Add a file to an existing library:\n<%= config.bin %> <%= command.id %> --library-id 1JDSG000007IbWX4A0 --file ./docs/new-guide.pdf --target-org myOrg"
+        "Add a file to an existing library:\n<%= config.bin %> <%= command.id %> -i 1JDSG000007IbWX4A0 --path ./docs/new-guide.pdf --target-org myOrg",
+        "Add multiple files:\n<%= config.bin %> <%= command.id %> -i 1JDSG000007IbWX4A0 --path ./docs/guide.pdf --path ./docs/faq.txt --target-org myOrg"
       ],
       "flags": {
         "json": {
@@ -3454,13 +3474,13 @@
           "multiple": false,
           "type": "option"
         },
-        "file": {
+        "path": {
           "char": "f",
-          "name": "file",
+          "name": "path",
           "required": true,
-          "summary": "Path to the file to add to the library.",
+          "summary": "Path to file(s) to add. Specify multiple times for batch upload.",
           "hasDynamicHelp": false,
-          "multiple": false,
+          "multiple": true,
           "type": "option"
         }
       },
@@ -3715,5 +3735,5 @@
       ]
     }
   },
-  "version": "1.42.0"
+  "version": "1.42.1"
 }