@W-22167805@ add sf agent trace delete command

[WillieRuemmele]

Work Item

@W-22167805@

Summary

Adds the sf agent trace delete command for deleting local trace files recorded during agent preview sessions. No org connection required.

Changes

• New command: sf agent trace delete
• Flags: --agent (substring match), --session-id, --older-than (e.g. 7d, 2w, 24h), --no-prompt
• Shows a preview table before deleting; prompts for confirmation unless --no-prompt is passed
• Messages: messages/agent.trace.delete.md
• Schema and snapshot updated

Files Changed

• src/commands/agent/trace/delete.ts
• messages/agent.trace.delete.md
• schemas/agent-trace-delete.json
• command-snapshot.json
• test/commands/agent/trace/delete.test.ts

Test Plan

• 22 unit tests passing
• npm run build and npm test pass cleanly
• Schema and deprecation snapshot regenerated

Dependencies

• Requires agents library PR: @W-22167805@ Add trace session utilities (listSessionTraces, readSessionTrace, readTurnIndex) forcedotcom/agents#273
• Stacks on top of list PR: @W-22167805@ add sf agent trace list command #409

[npiccolo]

QA Notes

Tested by merging wr/listTraces into wr/deleteTraces locally (since this PR stacks on top of it) and running NUTs against a scratch org on int-hub (admin@integrationtesthubna40.org) — the only devhub that supports the CustomerDataPlatform / Einstein1AIPlatform features required by the scratch def.

Build

The @salesforce/agents library was still at 1.2.0 on the wr/deleteTraces branch tip. After merging wr/listTraces, the published 1.6.0 (which includes listSessionTraces and TraceFileInfo) became available and the build passes.

One fix was required in src/commands/agent/trace/list.ts: ESLint's @typescript-eslint/no-unsafe-* rules flag listSessionTraces as returning any because the CJS re-export chain in the agents package isn't fully visible to ESLint's TS program. Added targeted // eslint-disable-next-line comments to suppress.

Unit Tests

3 unit tests in test/commands/agent/trace/delete.test.ts are currently failing due to hard-coded dates that have gone stale:

const RECENT_MTIME = new Date('2026-04-07T17:00:00.000Z'); // now ~31 days old

The test comments say "~23 days ago from 2026-04-30", but as of today (2026-05-08) RECENT_MTIME is ~31 days old, so it gets caught by the 30d and 4w --older-than filters when the tests expect it won't. Fix: use new Date(Date.now() - N_DAYS_MS) for relative dates.

NUTs

Ran yarn test:nuts --grep 'agent trace delete' three times — consistently 3 pass, 2 fail:

✅ returns empty array when no traces match the filter
❌ deletes traces for a specific session and returns deleted entries
❌ each deleted entry has required fields
✅ deletes traces older than a given duration with --older-than
✅ deletes all remaining traces with --no-prompt (cleanup)

Root Cause of NUT Failures

The 2 failing NUTs expose a design bug in the command itself. The before() hook runs agent preview start → agent preview send → agent preview end. The problem is that agent preview end calls removePreviewSessionCache, which deletes session-meta.json for the session.

agent trace delete uses listCachedPreviewSessions to discover sessions, and that function verifies each session by checking for the existence of session-meta.json. Since preview end removes it, the ended session is filtered out — and agent trace delete --session-id <endedSession> returns [].

The trace files are written to disk (confirmed by checking .sfdx/agents/), but the command can't find them because session-meta.json is gone.

Suggested fix: Either:

1. In @salesforce/agents — expose a function that lists sessions by scanning the filesystem directly (not gating on session-meta.json), or
2. In the command — add a fallback that scans .sfdx/agents/<agentId>/sessions/*/traces/*.json directly when listCachedPreviewSessions returns no results for a given --session-id.

[npiccolo]

QA Notes

Tested wr/deleteTraces merged with wr/listTraces (needed for @salesforce/agents@1.6.0 which ships listSessionTraces) against a scratch org on int-hub.

Flags

• --session-id
  ✅ Correctly filters to traces for the specified session only.
  ✅ Returns empty array when no session matches.

• --agent
  ✅ Case-insensitive substring match works correctly.
  ✅ Returns empty when no agents match.

• --older-than
  ✅ Accepts d, h, m, w units and all long-form variants.
  ✅ Correctly filters by file mtime — only deletes traces older than the cutoff.
  ✅ Returns empty when all traces are newer than the duration.
  ✅ Rejects invalid formats (no unit, non-numeric) with a helpful error message.

• --no-prompt
  ✅ Skips confirmation table and prompt, deletes directly.
  ✅ Without --no-prompt, shows a preview table and prompts for confirmation before deleting.
  ✅ Cancellation (no/cancel) leaves files untouched.

Unit Tests (after fixes)

✅ 189/189 passing

NUTs — run 4 times against int-hub scratch org

✅ 5/5 passing (after e9c21f9 + 1e32f60 fixes)

Bugs found during testing (now fixed)

1. Ended sessions were invisible — listCachedPreviewSessions gates on session-meta.json which preview end deletes. Fixed in e9c21f9 by scanning .sfdx/agents on disk directly.
2. NUT cwd mismatch — preview start/send/end were writing the session cache to the wrong directory. Fixed in 1e32f60 by passing cwd: session.project.dir to all preview calls.
3. Stale hard-coded dates in unit tests — RECENT_MTIME had gone past the 30d/4w thresholds. Fixed by switching to relative dates.