@W-22167805@ add sf agent trace delete command

command-snapshot.json

@@ -254,6 +254,14 @@
     ],
     "plugin": "@salesforce/plugin-agent"
   },
+  {
+    "alias": [],
+    "command": "agent:trace:delete",
+    "flagAliases": [],
+    "flagChars": ["a"],
+    "flags": ["agent", "flags-dir", "json", "no-prompt", "older-than", "session-id"],
+    "plugin": "@salesforce/plugin-agent"
+  },
   {
     "alias": [],
     "command": "agent:trace:list",
@@ -262,6 +270,14 @@
     "flags": ["agent", "flags-dir", "json", "session-id", "since"],
     "plugin": "@salesforce/plugin-agent"
   },
+  {
+    "alias": [],
+    "command": "agent:trace:read",
+    "flagAliases": [],
+    "flagChars": ["d", "f", "s", "t"],
+    "flags": ["dimension", "flags-dir", "format", "json", "session-id", "turn"],
+    "plugin": "@salesforce/plugin-agent"
+  },
   {
     "alias": [],
     "command": "agent:validate:authoring-bundle",

messages/agent.trace.delete.md

@@ -0,0 +1,87 @@
+# summary
+
+Delete agent preview trace files.
+
+# 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.
+
+Without 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).
+
+# flags.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.
+
+# flags.session-id.summary
+
+Only delete traces from this session ID.
+
+# flags.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).
+
+# flags.no-prompt.summary
+
+Skip the confirmation prompt and delete immediately.
+
+# error.invalidOlderThan
+
+Invalid --older-than value: '%s'. Use a number followed by a unit: m/minutes, h/hours, d/days, w/weeks (e.g. 7d, 24h, 30m, 2w).
+
+# prompt.confirm
+
+Delete %s trace file(s)? This cannot be undone.
+
+# output.noneFound
+
+No trace files matched the specified filters.
+
+# output.preview
+
+Found %s trace file(s) to delete:
+
+# output.cancelled
+
+Deletion cancelled.
+
+# output.deleted
+
+Deleted %s trace file(s).
+
+# output.tableHeader.agent
+
+Agent
+
+# output.tableHeader.sessionId
+
+Session ID
+
+# output.tableHeader.planId
+
+Plan ID
+
+# examples
+
+- Delete all traces for all agents and sessions (with confirmation prompt):
+
+  <%= config.bin %> <%= command.id %>
+
+- Delete all traces for a specific agent:
+
+  <%= config.bin %> <%= command.id %> --agent My_Agent
+
+- Delete traces from a specific session:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID>
+
+- Delete traces older than 7 days:
+
+  <%= config.bin %> <%= command.id %> --older-than 7d
+
+- Delete traces older than 24 hours for a specific agent, no prompt:
+
+  <%= config.bin %> <%= command.id %> --agent My_Agent --older-than 24h --no-prompt
+
+- Delete all traces without confirmation:
+
+  <%= config.bin %> <%= command.id %> --no-prompt

messages/agent.trace.read.md

@@ -0,0 +1,171 @@
+# summary
+
+Read and analyze trace files from an agent preview session.
+
+# description
+
+Reads trace files recorded during an agent preview session and outputs them in one of three formats.
+
+**--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.
+
+**--format detail**: Diagnostic drill-down into a specific dimension (--dimension required). Filters output to only the trace steps relevant to that dimension, minimizing noise.
+
+**--format raw**: Unprocessed trace JSON. Use this as a fallback when the trace schema has changed or you need to perform custom analysis.
+
+Available dimensions for --format detail: actions, grounding, routing, errors.
+
+Use --turn N to scope output to a single conversation turn.
+
+# flags.session-id.summary
+
+Session ID to read traces for.
+
+# flags.format.summary
+
+Output format: summary (default), detail, or raw. Use detail with --dimension to drill into a specific aspect of the trace.
+
+# flags.dimension.summary
+
+Dimension to drill into when using --format detail. One of: actions, grounding, routing, errors. Required when --format is detail.
+
+# flags.turn.summary
+
+Scope output to this conversation turn number.
+
+# error.detailRequiresDimension
+
+--format detail requires --dimension. Specify one of: actions, grounding, routing, errors.
+
+# error.sessionNotFound
+
+Session '%s' was not found in the local session cache. Run "sf agent trace list" to see available sessions.
+
+# error.turnIndexNotFound
+
+No turn index found for session '%s'. Cannot filter by --turn without a turn index.
+
+# error.turnNotFound
+
+Turn %s was not found in session '%s'.
+
+# error.parseFailedAll
+
+Trace parsing failed for all files: %s. The trace schema may have changed. Try --format raw to access unprocessed trace data.
+
+# warn.dimensionIgnored
+
+--dimension is ignored when --format is '%s'. Use --format detail to drill into a dimension.
+
+# warn.parseFailed
+
+Trace parsing failed for some files (skipped): %s. Try --format raw to access unprocessed trace data.
+
+# output.empty
+
+No traces found for this session.
+
+# output.emptyDimension
+
+No '%s' data found in the traces for this session.
+
+# output.tableHeader.turn
+
+Turn
+
+# output.tableHeader.topic
+
+Topic
+
+# output.tableHeader.userInput
+
+User Input
+
+# output.tableHeader.agentResponse
+
+Agent Response
+
+# output.tableHeader.actionsExecuted
+
+Actions Executed
+
+# output.tableHeader.latencyMs
+
+Latency
+
+# output.tableHeader.error
+
+Error
+
+# output.tableHeader.action
+
+Action
+
+# output.tableHeader.input
+
+Input
+
+# output.tableHeader.output
+
+Output
+
+# output.tableHeader.prompt
+
+Prompt
+
+# output.tableHeader.response
+
+Response
+
+# output.tableHeader.intent
+
+Intent
+
+# output.tableHeader.fromTopic
+
+From Topic
+
+# output.tableHeader.toTopic
+
+To Topic
+
+# output.tableHeader.source
+
+Source
+
+# output.tableHeader.errorCode
+
+Error Code
+
+# output.tableHeader.message
+
+Message
+
+# examples
+
+- Show a session summary (all turns):
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID>
+
+- Show summary for a single turn:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --turn 2
+
+- Drill into action execution across all turns:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension actions
+
+- Drill into routing decisions for a specific turn:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension routing --turn 1
+
+- Show all errors across the session:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format detail --dimension errors
+
+- Output raw trace JSON for custom parsing:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --format raw
+
+- Return results as JSON:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID> --json

schemas/agent-trace-delete.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/AgentTraceDeleteResult",
+  "definitions": {
+    "AgentTraceDeleteResult": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "agent": {
+            "type": "string"
+          },
+          "sessionId": {
+            "type": "string"
+          },
+          "planId": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          }
+        },
+        "required": ["agent", "sessionId", "planId", "path"],
+        "additionalProperties": false
+      }
+    }
+  }
+}