@salesforce/plugin-agent 1.36.1 → 1.38.0

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

@@ -0,0 +1,75 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { type PlannerResponse } from '@salesforce/agents';
+export declare const DIMENSIONS: readonly ["actions", "grounding", "routing", "errors"];
+export type Dimension = (typeof DIMENSIONS)[number];
+export type TurnSummary = {
+    turn: number;
+    planId: string;
+    topic: string;
+    userInput: string;
+    agentResponse: string;
+    actionsExecuted: string[];
+    latencyMs: number;
+    error: string | null;
+};
+export type ActionsRow = {
+    dimension: 'actions';
+    turn: number;
+    planId: string;
+    action: string;
+    input: string;
+    output: string;
+    latencyMs: number;
+    error: string | null;
+};
+export type GroundingRow = {
+    dimension: 'grounding';
+    turn: number;
+    planId: string;
+    prompt: string;
+    response: string;
+    latencyMs: number;
+};
+export type RoutingRow = {
+    dimension: 'routing';
+    turn: number;
+    planId: string;
+    fromTopic: string;
+    toTopic: string;
+    intent: string;
+};
+export type ErrorsRow = {
+    dimension: 'errors';
+    turn: number;
+    planId: string;
+    source: string;
+    errorCode: string;
+    message: string;
+};
+export type DimensionRow = ActionsRow | GroundingRow | RoutingRow | ErrorsRow;
+export type AgentTraceReadResult = {
+    sessionId: string;
+    format: 'summary' | 'detail' | 'raw';
+    dimension?: Dimension;
+    turns?: TurnSummary[];
+    detail?: DimensionRow[];
+    raw?: PlannerResponse[];
+};
+export default class AgentTraceRead extends SfCommand<AgentTraceReadResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly requiresProject = true;
+    static readonly flags: {
+        'session-id': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<"summary" | "detail" | "raw", import("@oclif/core/interfaces").CustomOptions>;
+        dimension: import("@oclif/core/interfaces").OptionFlag<"errors" | "actions" | "grounding" | "routing" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        turn: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<AgentTraceReadResult>;
+    private resolveAgentId;
+    private formatOutput;
+    private formatDetail;
+    private renderDetailTable;
+    private formatSummary;
+}

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

@@ -0,0 +1,308 @@
+/*
+ * 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 { Flags, SfCommand } from '@salesforce/sf-plugins-core';
+import { Messages, SfError } from '@salesforce/core';
+import { listSessionTraces, readSessionTrace, readTurnIndex, } from '@salesforce/agents';
+import { listAllAgentSessions } from '../../../agentSessionScanner.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@salesforce/plugin-agent', 'agent.trace.read');
+export const DIMENSIONS = ['actions', 'grounding', 'routing', 'errors'];
+const isFunctionStep = (s) => s.type === 'FunctionStep';
+const asFunctionWithErrors = (s) => s;
+function summarizeTurn(turn, planId, trace) {
+    const plan = trace.plan;
+    const userInput = plan.find((s) => s.type === 'UserInputStep');
+    const finalResponse = plan.find((s) => s.type === 'PlannerResponseStep');
+    const functionSteps = plan.filter(isFunctionStep).map(asFunctionWithErrors);
+    const errorStep = functionSteps.find((s) => s.function.errors?.length);
+    const errorMsg = errorStep?.function.errors?.[0]?.message ?? null;
+    const totalLatency = functionSteps.reduce((acc, s) => acc + (s.executionLatency ?? 0), 0);
+    return {
+        turn,
+        planId,
+        topic: trace.topic,
+        userInput: userInput?.type === 'UserInputStep' ? userInput.message : '',
+        agentResponse: finalResponse?.type === 'PlannerResponseStep' ? finalResponse.message : '',
+        actionsExecuted: functionSteps.map((s) => s.function.name),
+        latencyMs: totalLatency,
+        error: errorMsg,
+    };
+}
+function extractActions(turn, planId, trace) {
+    return trace.plan
+        .filter(isFunctionStep)
+        .map(asFunctionWithErrors)
+        .map((step) => ({
+        dimension: 'actions',
+        turn,
+        planId,
+        action: step.function.name,
+        input: JSON.stringify(step.function.input),
+        output: JSON.stringify(step.function.output),
+        latencyMs: step.executionLatency,
+        error: step.function.errors?.length ? step.function.errors[0].message : null,
+    }));
+}
+function extractGrounding(turn, planId, trace) {
+    return trace.plan
+        .filter((s) => s.type === 'LLMExecutionStep')
+        .filter((s) => s.promptName.includes('React'))
+        .map((step) => ({
+        dimension: 'grounding',
+        turn,
+        planId,
+        prompt: step.promptName,
+        response: step.promptResponse.slice(0, 500),
+        latencyMs: step.executionLatency,
+    }));
+}
+function extractRouting(turn, planId, trace) {
+    const topicStep = trace.plan.find((s) => s.type === 'UpdateTopicStep');
+    const eventStep = trace.plan.find((s) => s.type === 'EventStep' && s.eventName === 'topicChangeEvent');
+    const fromTopic = eventStep?.type === 'EventStep' ? eventStep.payload.oldTopic : 'null';
+    const toTopic = topicStep?.type === 'UpdateTopicStep' ? topicStep.topic : trace.topic;
+    return [{ dimension: 'routing', turn, planId, fromTopic, toTopic, intent: trace.intent }];
+}
+function extractErrors(turn, planId, trace) {
+    const rows = [];
+    for (const step of trace.plan) {
+        if (step.type === 'FunctionStep') {
+            const errors = asFunctionWithErrors(step).function.errors ?? [];
+            for (const e of errors) {
+                rows.push({
+                    dimension: 'errors',
+                    turn,
+                    planId,
+                    source: step.function.name,
+                    errorCode: e.statusCode,
+                    message: e.message,
+                });
+            }
+        }
+        if (step.type === 'EventStep' && step.isError) {
+            rows.push({
+                dimension: 'errors',
+                turn,
+                planId,
+                source: step.eventName,
+                errorCode: 'EVENT_ERROR',
+                message: JSON.stringify(step.payload),
+            });
+        }
+    }
+    return rows;
+}
+async function resolvePlanIds(agentId, sessionId, turn) {
+    const turnIndex = await readTurnIndex(agentId, sessionId);
+    if (turn !== undefined) {
+        // Try the turn index first (planId may be null if trace wasn't correlated)
+        const entry = turnIndex?.turns.find((t) => t.turn === turn && t.planId);
+        if (entry?.planId) {
+            return [{ turn: entry.turn, planId: entry.planId }];
+        }
+        // Fall back to positional order from trace files on disk
+        const traceFiles = await listSessionTraces(agentId, sessionId);
+        const byPosition = traceFiles[turn - 1];
+        if (!byPosition) {
+            throw new SfError(messages.getMessage('error.turnNotFound', [turn, sessionId]), 'TurnNotFound');
+        }
+        return [{ turn, planId: byPosition.planId }];
+    }
+    if (turnIndex) {
+        return turnIndex.turns.filter((t) => t.planId !== null).map((t) => ({ turn: t.turn, planId: t.planId }));
+    }
+    // Fall back to listing trace files when no turn index exists
+    const traceFiles = await listSessionTraces(agentId, sessionId);
+    return traceFiles.map((f, i) => ({ turn: i + 1, planId: f.planId }));
+}
+async function readTraces(agentId, sessionId, planIds) {
+    const traces = [];
+    const failedFiles = [];
+    for (const { turn, planId } of planIds) {
+        // eslint-disable-next-line no-await-in-loop
+        const trace = await readSessionTrace(agentId, sessionId, planId);
+        if (!trace?.plan || !Array.isArray(trace.plan)) {
+            failedFiles.push(planId);
+            continue;
+        }
+        traces.push({ turn, planId, trace });
+    }
+    return { traces, failedFiles };
+}
+function extractDimension(turn, planId, trace, dimension) {
+    if (dimension === 'actions')
+        return extractActions(turn, planId, trace);
+    if (dimension === 'grounding')
+        return extractGrounding(turn, planId, trace);
+    if (dimension === 'routing')
+        return extractRouting(turn, planId, trace);
+    return extractErrors(turn, planId, trace);
+}
+export default class AgentTraceRead extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static requiresProject = true;
+    static flags = {
+        'session-id': Flags.string({
+            summary: messages.getMessage('flags.session-id.summary'),
+            required: true,
+            char: 's',
+        }),
+        format: Flags.option({
+            options: ['summary', 'detail', 'raw'],
+            default: 'summary',
+            summary: messages.getMessage('flags.format.summary'),
+            char: 'f',
+        })(),
+        dimension: Flags.option({
+            options: DIMENSIONS,
+            summary: messages.getMessage('flags.dimension.summary'),
+            char: 'd',
+        })(),
+        turn: Flags.integer({
+            summary: messages.getMessage('flags.turn.summary'),
+            char: 't',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AgentTraceRead);
+        const sessionId = flags['session-id'];
+        if (flags.format === 'detail' && !flags.dimension) {
+            throw new SfError(messages.getMessage('error.detailRequiresDimension'), 'MissingDimension');
+        }
+        if (flags.dimension && flags.format !== 'detail') {
+            this.warn(messages.getMessage('warn.dimensionIgnored', [flags.format]));
+        }
+        const agentId = await this.resolveAgentId(sessionId);
+        const planIds = await resolvePlanIds(agentId, sessionId, flags.turn);
+        if (planIds.length === 0) {
+            this.log(messages.getMessage('output.empty'));
+            return { sessionId, format: flags.format, turns: [], detail: [], raw: [] };
+        }
+        const { traces, failedFiles } = await readTraces(agentId, sessionId, planIds);
+        if (failedFiles.length > 0 && traces.length === 0) {
+            throw new SfError(messages.getMessage('error.parseFailedAll', [failedFiles.join(', ')]), 'TraceParseError');
+        }
+        if (failedFiles.length > 0) {
+            this.warn(messages.getMessage('warn.parseFailed', [failedFiles.join(', ')]));
+        }
+        return this.formatOutput(sessionId, flags.format, flags.dimension, traces);
+    }
+    async resolveAgentId(sessionId) {
+        const allSessions = await listAllAgentSessions(this.project);
+        const entry = allSessions.find((s) => s.sessionId === sessionId);
+        if (!entry) {
+            throw new SfError(messages.getMessage('error.sessionNotFound', [sessionId]), 'SessionNotFound');
+        }
+        return entry.agentId;
+    }
+    formatOutput(sessionId, format, dimension, traces) {
+        if (format === 'raw') {
+            const raw = traces.map((t) => t.trace);
+            if (!this.jsonEnabled())
+                this.log(JSON.stringify(raw, null, 2));
+            return { sessionId, format: 'raw', raw };
+        }
+        if (format === 'detail') {
+            return this.formatDetail(sessionId, dimension, traces);
+        }
+        return this.formatSummary(sessionId, traces);
+    }
+    formatDetail(sessionId, dimension, traces) {
+        const detail = traces.flatMap(({ turn, planId, trace }) => extractDimension(turn, planId, trace, dimension));
+        if (detail.length === 0) {
+            this.log(messages.getMessage('output.emptyDimension', [dimension]));
+            return { sessionId, format: 'detail', dimension, detail: [] };
+        }
+        if (!this.jsonEnabled()) {
+            this.renderDetailTable(dimension, detail);
+        }
+        return { sessionId, format: 'detail', dimension, detail };
+    }
+    renderDetailTable(dimension, detail) {
+        if (dimension === 'actions') {
+            this.table({
+                data: detail,
+                columns: [
+                    { key: 'turn', name: messages.getMessage('output.tableHeader.turn') },
+                    { key: 'action', name: messages.getMessage('output.tableHeader.action') },
+                    { key: 'input', name: messages.getMessage('output.tableHeader.input') },
+                    { key: 'output', name: messages.getMessage('output.tableHeader.output') },
+                    { key: 'latencyMs', name: messages.getMessage('output.tableHeader.latencyMs') },
+                    { key: 'error', name: messages.getMessage('output.tableHeader.error') },
+                ],
+            });
+        }
+        else if (dimension === 'grounding') {
+            this.table({
+                data: detail,
+                columns: [
+                    { key: 'turn', name: messages.getMessage('output.tableHeader.turn') },
+                    { key: 'prompt', name: messages.getMessage('output.tableHeader.prompt') },
+                    { key: 'response', name: messages.getMessage('output.tableHeader.response') },
+                    { key: 'latencyMs', name: messages.getMessage('output.tableHeader.latencyMs') },
+                ],
+            });
+        }
+        else if (dimension === 'routing') {
+            this.table({
+                data: detail,
+                columns: [
+                    { key: 'turn', name: messages.getMessage('output.tableHeader.turn') },
+                    { key: 'intent', name: messages.getMessage('output.tableHeader.intent') },
+                    { key: 'fromTopic', name: messages.getMessage('output.tableHeader.fromTopic') },
+                    { key: 'toTopic', name: messages.getMessage('output.tableHeader.toTopic') },
+                ],
+            });
+        }
+        else {
+            this.table({
+                data: detail,
+                columns: [
+                    { key: 'turn', name: messages.getMessage('output.tableHeader.turn') },
+                    { key: 'source', name: messages.getMessage('output.tableHeader.source') },
+                    { key: 'errorCode', name: messages.getMessage('output.tableHeader.errorCode') },
+                    { key: 'message', name: messages.getMessage('output.tableHeader.message') },
+                ],
+            });
+        }
+    }
+    formatSummary(sessionId, traces) {
+        const turns = traces.map(({ turn, planId, trace }) => summarizeTurn(turn, planId, trace));
+        if (!this.jsonEnabled()) {
+            this.table({
+                data: turns.map((t) => ({
+                    ...t,
+                    actionsExecuted: t.actionsExecuted.join(', ') || '—',
+                    error: t.error ?? '—',
+                    latencyMs: `${t.latencyMs}ms`,
+                })),
+                columns: [
+                    { key: 'turn', name: messages.getMessage('output.tableHeader.turn') },
+                    { key: 'topic', name: messages.getMessage('output.tableHeader.topic') },
+                    { key: 'userInput', name: messages.getMessage('output.tableHeader.userInput') },
+                    { key: 'agentResponse', name: messages.getMessage('output.tableHeader.agentResponse') },
+                    { key: 'actionsExecuted', name: messages.getMessage('output.tableHeader.actionsExecuted') },
+                    { key: 'latencyMs', name: messages.getMessage('output.tableHeader.latencyMs') },
+                    { key: 'error', name: messages.getMessage('output.tableHeader.error') },
+                ],
+            });
+        }
+        return { sessionId, format: 'summary', turns };
+    }
+}
+//# sourceMappingURL=read.js.map

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

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

package/messages/agent.test.run-eval.md

@@ -20,10 +20,6 @@ Path to test spec file (YAML or JSON). Supports reading from stdin when piping c
 
 Agent DeveloperName (also called API name) to resolve agent_id and agent_version_id. Auto-inferred from the YAML spec's subjectName.
 
-# flags.wait.summary
-
-Number of minutes to wait for results.
-
 # flags.result-format.summary
 
 Format of the agent test results.

package/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

package/messages/agent.trace.list.md

@@ -0,0 +1,87 @@
+# summary
+
+List the trace files that were recorded during all agent preview sessions.
+
+# description
+
+Lists trace files recorded during agent preview sessions. By default, lists all traces for all agents and all of their sessions. Use flags to narrow results: filter by agent name (--agent), by session (--session-id), or by date (--since).
+
+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.
+
+# flags.agent.summary
+
+Only show traces for this agent name (substring match). Matches against the name used when starting the session, whether that's an authoring bundle or a published agent API name.
+
+# flags.session-id.summary
+
+Session ID used to filter the list of trace files.
+
+# flags.since.summary
+
+Date used to filter the list of trace files; only those recorded on or after the date are listed.
+
+# flags.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.
+
+# error.invalidSince
+
+Invalid --since value: '%s'. Use ISO 8601 format — date-only (2026-04-20), date-time (2026-04-20T14:00:00Z), or with milliseconds (2026-04-20T14:00:00.000Z). The "Recorded At" values shown in the table output are valid inputs.
+
+# output.empty
+
+No trace files found.
+
+# output.tableHeader.agent
+
+Agent
+
+# output.tableHeader.sessionId
+
+Session ID
+
+# output.tableHeader.planId
+
+Plan ID
+
+# output.tableHeader.mtime
+
+Recorded At
+
+# output.tableHeader.size
+
+Size
+
+# output.tableHeader.path
+
+Path
+
+# examples
+
+- List all traces for all agents and sessions:
+
+  <%= config.bin %> <%= command.id %>
+
+- List all traces for a specific agent:
+
+  <%= config.bin %> <%= command.id %> --agent My_Agent
+
+- List traces for a specific session:
+
+  <%= config.bin %> <%= command.id %> --session-id <SESSION_ID>
+
+- List traces recorded on or after April 20, 2026 (date-only, interpreted as UTC midnight):
+
+  <%= config.bin %> <%= command.id %> --since 2026-04-20
+
+- List traces recorded on or after a specific UTC time:
+
+  <%= config.bin %> <%= command.id %> --since 2026-04-20T14:00:00Z
+
+- Filter by agent and date together:
+
+  <%= config.bin %> <%= command.id %> --agent My_Agent --since 2026-04-20
+
+- Return results as JSON:
+
+  <%= config.bin %> <%= command.id %> --json