@salesforce/plugin-agent 1.37.0 → 1.38.0

package/README.md

@@ -78,6 +78,9 @@ sf plugins
 - [`sf agent test resume`](#sf-agent-test-resume)
 - [`sf agent test run`](#sf-agent-test-run)
 - [`sf agent test run-eval`](#sf-agent-test-run-eval)
+- [`sf agent trace delete`](#sf-agent-trace-delete)
+- [`sf agent trace list`](#sf-agent-trace-list)
+- [`sf agent trace read`](#sf-agent-trace-read)
 - [`sf agent validate authoring-bundle`](#sf-agent-validate-authoring-bundle)
 
 ## `sf agent activate`
@@ -127,7 +130,7 @@ EXAMPLES
     $ sf agent activate --api-name Resort_Manager --version 2 --target-org my-org
 ```
 
-_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/activate.ts)_
+_See code: [src/commands/agent/activate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/activate.ts)_
 
 ## `sf agent create`
 
@@ -194,7 +197,7 @@ EXAMPLES
     $ sf agent create --name "Resort Manager" --spec specs/resortManagerAgent.yaml --preview
 ```
 
-_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/create.ts)_
+_See code: [src/commands/agent/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/create.ts)_
 
 ## `sf agent deactivate`
 
@@ -235,7 +238,7 @@ EXAMPLES
     $ sf agent deactivate --api-name Resort_Manager --target-org my-org
 ```
 
-_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/deactivate.ts)_
+_See code: [src/commands/agent/deactivate.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/deactivate.ts)_
 
 ## `sf agent generate agent-spec`
 
@@ -342,7 +345,7 @@ EXAMPLES
     $ sf agent generate agent-spec --tone formal --agent-user resortmanager@myorg.com
 ```
 
-_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/generate/agent-spec.ts)_
+_See code: [src/commands/agent/generate/agent-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/agent-spec.ts)_
 
 ## `sf agent generate authoring-bundle`
 
@@ -419,7 +422,7 @@ EXAMPLES
       other-package-dir/main/default --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/generate/authoring-bundle.ts)_
+_See code: [src/commands/agent/generate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/authoring-bundle.ts)_
 
 ## `sf agent generate template`
 
@@ -481,7 +484,7 @@ EXAMPLES
       my-package --source-org my-scratch-org
 ```
 
-_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/generate/template.ts)_
+_See code: [src/commands/agent/generate/template.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/template.ts)_
 
 ## `sf agent generate test-spec`
 
@@ -546,7 +549,7 @@ EXAMPLES
       force-app//main/default/aiEvaluationDefinitions/Resort_Manager_Tests.aiEvaluationDefinition-meta.xml
 ```
 
-_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/generate/test-spec.ts)_
+_See code: [src/commands/agent/generate/test-spec.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/generate/test-spec.ts)_
 
 ## `sf agent preview`
 
@@ -619,7 +622,7 @@ EXAMPLES
     $ sf agent preview --use-live-actions --apex-debug --output-dir transcripts/my-preview
 ```
 
-_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/preview.ts)_
+_See code: [src/commands/agent/preview.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview.ts)_
 
 ## `sf agent preview end`
 
@@ -674,7 +677,7 @@ EXAMPLES
     $ sf agent preview end --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/preview/end.ts)_
+_See code: [src/commands/agent/preview/end.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/end.ts)_
 
 ## `sf agent preview send`
 
@@ -732,7 +735,7 @@ EXAMPLES
     $ sf agent preview send --utterance "what can you help me with?" --authoring-bundle My_Local_Agent
 ```
 
-_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/preview/send.ts)_
+_See code: [src/commands/agent/preview/send.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/send.ts)_
 
 ## `sf agent preview sessions`
 
@@ -765,7 +768,7 @@ EXAMPLES
     $ sf agent preview sessions
 ```
 
-_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/preview/sessions.ts)_
+_See code: [src/commands/agent/preview/sessions.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/sessions.ts)_
 
 ## `sf agent preview start`
 
@@ -830,7 +833,7 @@ EXAMPLES
     $ sf agent preview start --api-name My_Published_Agent
 ```
 
-_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/preview/start.ts)_
+_See code: [src/commands/agent/preview/start.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/preview/start.ts)_
 
 ## `sf agent publish authoring-bundle`
 
@@ -890,7 +893,7 @@ EXAMPLES
     $ sf agent publish authoring-bundle --api-name MyAuthoringbundle --concise
 ```
 
-_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/publish/authoring-bundle.ts)_
+_See code: [src/commands/agent/publish/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/publish/authoring-bundle.ts)_
 
 ## `sf agent test create`
 
@@ -945,7 +948,7 @@ EXAMPLES
     $ sf agent test create --spec specs/Resort_Manager-testSpec.yaml --api-name Resort_Manager_Test --preview
 ```
 
-_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/create.ts)_
+_See code: [src/commands/agent/test/create.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/create.ts)_
 
 ## `sf agent test list`
 
@@ -980,7 +983,7 @@ EXAMPLES
     $ sf agent test list --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/list.ts)_
+_See code: [src/commands/agent/test/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/list.ts)_
 
 ## `sf agent test results`
 
@@ -1056,7 +1059,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/results.ts)_
+_See code: [src/commands/agent/test/results.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/results.ts)_
 
 ## `sf agent test resume`
 
@@ -1140,7 +1143,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/resume.ts)_
+_See code: [src/commands/agent/test/resume.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/resume.ts)_
 
 ## `sf agent test run`
 
@@ -1224,7 +1227,7 @@ FLAG DESCRIPTIONS
     expression when using custom evaluations.
 ```
 
-_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/run.ts)_
+_See code: [src/commands/agent/test/run.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/run.ts)_
 
 ## `sf agent test run-eval`
 
@@ -1297,7 +1300,205 @@ EXAMPLES
   $ echo '{"tests":[...]}' | sf agent test run-eval --spec --target-org my-org
 ```
 
-_See code: [src/commands/agent/test/run-eval.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/test/run-eval.ts)_
+_See code: [src/commands/agent/test/run-eval.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/test/run-eval.ts)_
+
+## `sf agent trace delete`
+
+Delete agent preview trace files.
+
+```
+USAGE
+  $ sf agent trace delete [--json] [--flags-dir <value>] [-a <value>] [--session-id <value>] [--older-than <value>]
+    [--no-prompt]
+
+FLAGS
+  -a, --agent=<value>       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.
+      --no-prompt           Skip the confirmation prompt and delete immediately.
+      --older-than=<value>  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).
+      --session-id=<value>  Only delete traces from this session ID.
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
+
+DESCRIPTION
+  Delete agent preview trace files.
+
+  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).
+
+EXAMPLES
+  Delete all traces for all agents and sessions (with confirmation prompt):
+
+    $ sf agent trace delete
+
+  Delete all traces for a specific agent:
+
+    $ sf agent trace delete --agent My_Agent
+
+  Delete traces from a specific session:
+
+    $ sf agent trace delete --session-id <SESSION_ID>
+
+  Delete traces older than 7 days:
+
+    $ sf agent trace delete --older-than 7d
+
+  Delete traces older than 24 hours for a specific agent, no prompt:
+
+    $ sf agent trace delete --agent My_Agent --older-than 24h --no-prompt
+
+  Delete all traces without confirmation:
+
+    $ sf agent trace delete --no-prompt
+```
+
+_See code: [src/commands/agent/trace/delete.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/delete.ts)_
+
+## `sf agent trace list`
+
+List the trace files that were recorded during all agent preview sessions.
+
+```
+USAGE
+  $ sf agent trace list [--json] [--flags-dir <value>] [--session-id <value>] [-a <value>] [--since <value>]
+
+FLAGS
+  -a, --agent=<value>       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.
+      --session-id=<value>  Session ID used to filter the list of trace files.
+      --since=<value>       Date used to filter the list of trace files; only those recorded on or after the date are
+                            listed.
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
+
+DESCRIPTION
+  List the trace files that were recorded during all agent preview sessions.
+
+  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).
+
+  Each 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 traces for all agents and sessions:
+
+    $ sf agent trace list
+
+  List all traces for a specific agent:
+
+    $ sf agent trace list --agent My_Agent
+
+  List traces for a specific session:
+
+    $ sf agent trace list --session-id <SESSION_ID>
+
+  List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
+
+    $ sf agent trace list --since 2026-04-20
+
+  List traces recorded on or after a specific UTC time:
+
+    $ sf agent trace list --since 2026-04-20T14:00:00Z
+
+  Filter by agent and date together:
+
+    $ sf agent trace list --agent My_Agent --since 2026-04-20
+
+  Return results as JSON:
+
+    $ sf agent trace list --json
+
+FLAG DESCRIPTIONS
+  --since=<value>  Date used to filter the list of trace files; only those recorded on or after the date are listed.
+
+    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.
+```
+
+_See code: [src/commands/agent/trace/list.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/list.ts)_
+
+## `sf agent trace read`
+
+Read and analyze trace files from an agent preview session.
+
+```
+USAGE
+  $ sf agent trace read -s <value> [--json] [--flags-dir <value>] [-f summary|detail|raw] [-d
+    actions|grounding|routing|errors] [-t <value>]
+
+FLAGS
+  -d, --dimension=<option>  Dimension to drill into when using --format detail. One of: actions, grounding, routing,
+                            errors. Required when --format is detail.
+                            <options: actions|grounding|routing|errors>
+  -f, --format=<option>     [default: summary] Output format: summary (default), detail, or raw. Use detail with
+                            --dimension to drill into a specific aspect of the trace.
+                            <options: summary|detail|raw>
+  -s, --session-id=<value>  (required) Session ID to read traces for.
+  -t, --turn=<value>        Scope output to this conversation turn number.
+
+GLOBAL FLAGS
+  --flags-dir=<value>  Import flag values from a directory.
+  --json               Format output as json.
+
+DESCRIPTION
+  Read and analyze trace files from an agent preview session.
+
+  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.
+
+EXAMPLES
+  Show a session summary (all turns):
+
+    $ sf agent trace read --session-id <SESSION_ID>
+
+  Show summary for a single turn:
+
+    $ sf agent trace read --session-id <SESSION_ID> --turn 2
+
+  Drill into action execution across all turns:
+
+    $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension actions
+
+  Drill into routing decisions for a specific turn:
+
+    $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension routing --turn 1
+
+  Show all errors across the session:
+
+    $ sf agent trace read --session-id <SESSION_ID> --format detail --dimension errors
+
+  Output raw trace JSON for custom parsing:
+
+    $ sf agent trace read --session-id <SESSION_ID> --format raw
+
+  Return results as JSON:
+
+    $ sf agent trace read --session-id <SESSION_ID> --json
+```
+
+_See code: [src/commands/agent/trace/read.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/trace/read.ts)_
 
 ## `sf agent validate authoring-bundle`
 
@@ -1344,6 +1545,6 @@ EXAMPLES
     $ sf agent validate authoring-bundle --api-name MyAuthoringBundle --target-org my-dev-org
 ```
 
-_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.37.0/src/commands/agent/validate/authoring-bundle.ts)_
+_See code: [src/commands/agent/validate/authoring-bundle.ts](https://github.com/salesforcecli/plugin-agent/blob/1.38.0/src/commands/agent/validate/authoring-bundle.ts)_
 
 <!-- commandsstop -->

package/lib/agentSessionScanner.d.ts

@@ -0,0 +1,12 @@
+import { type SfProject } from '@salesforce/core';
+export type AgentSession = {
+    agentId: string;
+    displayName: string;
+    sessionId: string;
+};
+/**
+ * Returns all sessions that have trace data on disk — both active sessions (still in the
+ * cache index) and ended sessions (removed from the index by `agent preview end` but whose
+ * trace directories remain under .sfdx/agents/<agentId>/sessions/<sessionId>/).
+ */
+export declare function listAllAgentSessions(project: SfProject): Promise<AgentSession[]>;

package/lib/agentSessionScanner.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listCachedPreviewSessions } from '@salesforce/agents';
+/**
+ * Returns all sessions that have trace data on disk — both active sessions (still in the
+ * cache index) and ended sessions (removed from the index by `agent preview end` but whose
+ * trace directories remain under .sfdx/agents/<agentId>/sessions/<sessionId>/).
+ */
+export async function listAllAgentSessions(project) {
+    const cached = await listCachedPreviewSessions(project);
+    const active = cached.flatMap(({ agentId, displayName, sessions }) => sessions.map(({ sessionId }) => ({ agentId, displayName: displayName ?? agentId, sessionId })));
+    const seen = new Set(active.map((s) => s.sessionId));
+    const agentsDir = join(project.getPath(), '.sfdx', 'agents');
+    const ended = [];
+    try {
+        const agentDirs = await readdir(agentsDir, { withFileTypes: true });
+        for (const agentEnt of agentDirs) {
+            if (!agentEnt.isDirectory())
+                continue;
+            const sessionsDir = join(agentsDir, agentEnt.name, 'sessions');
+            try {
+                // eslint-disable-next-line no-await-in-loop
+                const sessionDirs = await readdir(sessionsDir, { withFileTypes: true });
+                for (const sessEnt of sessionDirs) {
+                    if (!sessEnt.isDirectory() || seen.has(sessEnt.name))
+                        continue;
+                    ended.push({ agentId: agentEnt.name, displayName: agentEnt.name, sessionId: sessEnt.name });
+                    seen.add(sessEnt.name);
+                }
+            }
+            catch {
+                // no sessions dir for this agent
+            }
+        }
+    }
+    catch {
+        // no .sfdx/agents dir yet
+    }
+    return [...active, ...ended];
+}
+//# sourceMappingURL=agentSessionScanner.js.map

package/lib/agentSessionScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentSessionScanner.js","sourceRoot":"","sources":["../src/agentSessionScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAI/D;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAkB;IAC3D,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,MAAM,GAAmB,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE,CACnF,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAC/F,CAAC;IAEF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAErD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE;gBAAE,SAAS;YACtC,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YAC/D,IAAI,CAAC;gBACH,4CAA4C;gBAC5C,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxE,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;oBAClC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC;wBAAE,SAAS;oBAC/D,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;oBAC5F,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,iCAAiC;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;AAC/B,CAAC"}

package/lib/commands/agent/trace/delete.d.ts

@@ -0,0 +1,21 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+export type AgentTraceDeleteResult = Array<{
+    agent: string;
+    sessionId: string;
+    planId: string;
+    path: string;
+}>;
+export default class AgentTraceDelete extends SfCommand<AgentTraceDeleteResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly requiresProject = true;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
+    static readonly flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'session-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'older-than': import("@oclif/core/interfaces").OptionFlag<Date | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-prompt': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<AgentTraceDeleteResult>;
+}

package/lib/commands/agent/trace/delete.js

@@ -0,0 +1,118 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { unlink } from 'node:fs/promises';
+import { Flags, SfCommand, toHelpSection } from '@salesforce/sf-plugins-core';
+import { Messages, SfError } from '@salesforce/core';
+import { listSessionTraces } from '@salesforce/agents';
+import yesNoOrCancel from '../../../yes-no-cancel.js';
+import { listAllAgentSessions } from '../../../agentSessionScanner.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.trace.delete');
+const DURATION_RE = /^(\d+)(d|h|m|w|days?|hours?|minutes?|weeks?)$/i;
+const UNIT_MS = {
+    m: 60_000,
+    minute: 60_000,
+    minutes: 60_000,
+    h: 3_600_000,
+    hour: 3_600_000,
+    hours: 3_600_000,
+    d: 86_400_000,
+    day: 86_400_000,
+    days: 86_400_000,
+    w: 604_800_000,
+    week: 604_800_000,
+    weeks: 604_800_000,
+};
+export default class AgentTraceDelete extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static requiresProject = true;
+    static errorCodes = toHelpSection('ERROR CODES', {
+        'Succeeded (0)': 'Traces deleted successfully (or no traces matched).',
+    });
+    static flags = {
+        agent: Flags.string({
+            summary: messages.getMessage('flags.agent.summary'),
+            char: 'a',
+        }),
+        'session-id': Flags.string({
+            summary: messages.getMessage('flags.session-id.summary'),
+        }),
+        'older-than': Flags.custom({
+            summary: messages.getMessage('flags.older-than.summary'),
+            // eslint-disable-next-line @typescript-eslint/require-await
+            parse: async (raw) => {
+                const match = DURATION_RE.exec(raw);
+                if (!match) {
+                    throw new SfError(messages.getMessage('error.invalidOlderThan', [raw]), 'InvalidDuration');
+                }
+                const ms = parseInt(match[1], 10) * UNIT_MS[match[2].toLowerCase()];
+                return new Date(Date.now() - ms);
+            },
+        })(),
+        'no-prompt': Flags.boolean({
+            summary: messages.getMessage('flags.no-prompt.summary'),
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AgentTraceDelete);
+        const agentFilter = flags.agent?.toLowerCase();
+        const allSessions = await listAllAgentSessions(this.project);
+        const candidates = [];
+        for (const { agentId, displayName, sessionId } of allSessions) {
+            if (agentFilter && !displayName.toLowerCase().includes(agentFilter))
+                continue;
+            if (flags['session-id'] && sessionId !== flags['session-id'])
+                continue;
+            // eslint-disable-next-line no-await-in-loop
+            let traces = await listSessionTraces(agentId, sessionId);
+            if (flags['older-than']) {
+                traces = traces.filter((t) => t.mtime < flags['older-than']);
+            }
+            for (const t of traces) {
+                candidates.push({ agent: displayName, sessionId, planId: t.planId, path: t.path });
+            }
+        }
+        if (candidates.length === 0) {
+            this.log(messages.getMessage('output.noneFound'));
+            return [];
+        }
+        if (!flags['no-prompt']) {
+            this.log(messages.getMessage('output.preview', [candidates.length]));
+            this.table({
+                data: candidates.map((c) => ({ agent: c.agent, sessionId: c.sessionId, planId: c.planId })),
+                columns: [
+                    { key: 'agent', name: messages.getMessage('output.tableHeader.agent') },
+                    { key: 'sessionId', name: messages.getMessage('output.tableHeader.sessionId') },
+                    { key: 'planId', name: messages.getMessage('output.tableHeader.planId') },
+                ],
+            });
+            const confirmed = await yesNoOrCancel({
+                message: messages.getMessage('prompt.confirm', [candidates.length]),
+                default: false,
+            });
+            if (confirmed === 'cancel' || confirmed === false) {
+                this.log(messages.getMessage('output.cancelled'));
+                return [];
+            }
+        }
+        await Promise.all(candidates.map((c) => unlink(c.path)));
+        this.log(messages.getMessage('output.deleted', [candidates.length]));
+        return candidates;
+    }
+}
+//# sourceMappingURL=delete.js.map

package/lib/commands/agent/trace/delete.js.map

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

package/lib/commands/agent/trace/list.d.ts

@@ -0,0 +1,22 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+export type AgentTraceListResult = Array<{
+    agent: string;
+    sessionId: string;
+    planId: string;
+    path: string;
+    size: number;
+    mtime: string;
+}>;
+export default class AgentTraceList extends SfCommand<AgentTraceListResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly requiresProject = true;
+    static readonly errorCodes: import("@oclif/core").HelpSection;
+    static readonly flags: {
+        'session-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        agent: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        since: import("@oclif/core/interfaces").OptionFlag<Date | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AgentTraceListResult>;
+}