@salesforce/agents 0.19.7 → 0.20.0-beta.2

package/lib/{agentPublisher.d.ts → agents/scriptAgentPublisher.d.ts}

@@ -1,16 +1,22 @@
 import { Connection, SfProject } from '@salesforce/core';
-import { type AgentJson, type PublishAgent } from './types.js';
+import { type AgentJson, type PublishAgent } from '../types';
 /**
  * Service class responsible for publishing agents to Salesforce orgs
  */
-export declare class AgentPublisher {
+export declare class ScriptAgentPublisher {
     private readonly maybeMock;
-    private connection;
+    private readonly connection;
     private project;
-    private agentJson;
-    private developerName;
-    private bundleMetaPath;
+    private readonly agentJson;
+    private readonly developerName;
+    private readonly bundleMetaPath;
     private bundleDir;
+    /**
+     * Original connection username, stored to create fresh connections for metadata operations.
+     * This ensures metadata operations (retrieve/deploy) use a standard connection that hasn't
+     * been upgraded with JWT, which is required for SOAP API operations.
+     */
+    private readonly originalUsername;
     private API_URL;
     private readonly API_HEADERS;
     /**
@@ -18,6 +24,7 @@ export declare class AgentPublisher {
      *
      * @param connection The connection to the Salesforce org
      * @param project The Salesforce project
+     * @param agentJson
      */
     constructor(connection: Connection, project: SfProject, agentJson: AgentJson);
     /**
@@ -26,6 +33,14 @@ export declare class AgentPublisher {
      * @returns Promise<PublishAgent> The publish response
      */
     publishAgentJson(): Promise<PublishAgent>;
+    /**
+     * Creates a fresh standard connection for metadata operations (retrieve/deploy).
+     * This ensures metadata operations use a connection that hasn't been upgraded with JWT,
+     * which is required for SOAP API operations.
+     *
+     * @returns A fresh Connection instance with standard authentication
+     */
+    private createStandardConnection;
     /**
      * Validates and extracts the developer name from the agent configuration,
      * and locates the corresponding authoring bundle directory and metadata file.
@@ -41,8 +56,8 @@ export declare class AgentPublisher {
     /**
      * Retrieve the agent metadata from the org after publishing
      *
-     * @param developerName The developer name of the agent
-     * @param originalConnection The original connection to use for retrieval
+     * @param botVersionName The bot version name
+     * @param connection
      */
     private retrieveAgentMetadata;
     /**
@@ -53,6 +68,7 @@ export declare class AgentPublisher {
      * 2. Second deployment with target attribute commits the AAB as the published version
      *
      * @param botVersionName The bot version name to use as the target for the final published deployment
+     * @param connection
      * @private
      */
     private syncAuthoringBundle;
@@ -61,9 +77,9 @@ export declare class AgentPublisher {
      * The target attribute is required for deployment but should not remain in the
      * local source files after deployment.
      *
-     * @param botVersionId The bot version ID used to construct the target attribute
-     *
      * @throws SfError if the deployment fails or if there are component deployment errors
+     * @param botVersionName
+     * @param connection
      */
     private deployAuthoringBundle;
     /**

package/lib/{agentPublisher.js → agents/scriptAgentPublisher.js}

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright 2025, Salesforce, Inc.
+ * 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.
@@ -48,16 +48,15 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentPublisher = void 0;
+exports.ScriptAgentPublisher = void 0;
 const path = __importStar(require("node:path"));
 const promises_1 = require("node:fs/promises");
 const node_fs_1 = require("node:fs");
-const kit_1 = require("@salesforce/kit");
 const fast_xml_parser_1 = require("fast-xml-parser");
 const core_1 = require("@salesforce/core");
 const source_deploy_retrieve_1 = require("@salesforce/source-deploy-retrieve");
-const maybe_mock_1 = require("./maybe-mock");
-const utils_1 = require("./utils");
+const maybe_mock_1 = require("../maybe-mock");
+const utils_1 = require("../utils");
 ;
 const messages = new core_1.Messages('@salesforce/agents', 'agentPublisher', new Map([["agentRetrievalError", "Unable to retrieve newly created Agent metadata. Due to: %s"], ["agentRetrievalErrorActions", "Retrieve the agent metadata using the \"project retrieve start\" command."], ["authoringBundleDeploymentError", "Unable to deploy AiAuthoringBundle metadata. Due to: %s"], ["authoringBundleDeploymentErrorActions", "Deploy the authoring bundle metadata using the \"project deploy start\" command."], ["findBotVersionError", "Unable to find BotVersion with id %s."]]));
 let logger;
@@ -70,7 +69,7 @@ const getLogger = () => {
 /**
  * Service class responsible for publishing agents to Salesforce orgs
  */
-class AgentPublisher {
+class ScriptAgentPublisher {
     maybeMock;
     connection;
     project;
@@ -78,7 +77,13 @@ class AgentPublisher {
     developerName;
     bundleMetaPath;
     bundleDir;
-    API_URL = `https://${kit_1.env.getBoolean('SF_TEST_API') ? 'test.' : ''}api.salesforce.com/einstein/ai-agent/v1.1/authoring/agents`;
+    /**
+     * Original connection username, stored to create fresh connections for metadata operations.
+     * This ensures metadata operations (retrieve/deploy) use a standard connection that hasn't
+     * been upgraded with JWT, which is required for SOAP API operations.
+     */
+    originalUsername;
+    API_URL = `https://${(0, utils_1.getEndpoint)()}api.salesforce.com/einstein/ai-agent/v1.1/authoring/agents`;
     API_HEADERS = {
         'x-client-name': 'afdx',
         'content-type': 'application/json',
@@ -88,12 +93,15 @@ class AgentPublisher {
      *
      * @param connection The connection to the Salesforce org
      * @param project The Salesforce project
+     * @param agentJson
      */
     constructor(connection, project, agentJson) {
         this.maybeMock = new maybe_mock_1.MaybeMock(connection);
         this.connection = connection;
         this.project = project;
         this.agentJson = agentJson;
+        // Store the original username to create fresh connections for metadata operations
+        this.originalUsername = connection.getUsername();
         // Validate and get developer name and bundle directory
         const validationResult = this.validateDeveloperName();
         this.developerName = validationResult.developerName;
@@ -117,8 +125,9 @@ class AgentPublisher {
         // before metadata operations that may use SOAP API
         let response;
         try {
-            await (0, utils_1.useNamedUserJwt)(this.connection);
             const botId = await this.getPublishedBotId(this.developerName);
+            // if we've found a botId in the org, then this agent has already been published before => ai-agent/v1.1/authoring/agents/<id>/versions
+            // if we didn't find an Id in the org, then we're publishing for the first time         => ai-agent/v1.1/authoring/agents
             const url = botId ? `${this.API_URL}/${botId}/versions` : this.API_URL;
             response = await this.maybeMock.request('POST', url, body, this.API_HEADERS);
         }
@@ -132,8 +141,9 @@ class AgentPublisher {
             // 1. retrieve the new Agent metadata that's in the org
             // 2. deploy the AuthoringBundle's -meta.xml file with correct target attribute
             const botVersionName = await this.getVersionDeveloperName(response.botVersionId);
-            await this.retrieveAgentMetadata(botVersionName);
-            await this.syncAuthoringBundle(botVersionName);
+            const standardConnection = await this.createStandardConnection();
+            await this.retrieveAgentMetadata(botVersionName, standardConnection);
+            await this.syncAuthoringBundle(botVersionName, standardConnection);
             return { ...response, developerName: this.developerName };
         }
         else {
@@ -144,6 +154,21 @@ class AgentPublisher {
             });
         }
     }
+    /**
+     * Creates a fresh standard connection for metadata operations (retrieve/deploy).
+     * This ensures metadata operations use a connection that hasn't been upgraded with JWT,
+     * which is required for SOAP API operations.
+     *
+     * @returns A fresh Connection instance with standard authentication
+     */
+    async createStandardConnection() {
+        const authInfo = await core_1.AuthInfo.create({
+            username: this.originalUsername,
+        });
+        return core_1.Connection.create({
+            authInfo,
+        });
+    }
     /**
      * Validates and extracts the developer name from the agent configuration,
      * and locates the corresponding authoring bundle directory and metadata file.
@@ -178,10 +203,10 @@ class AgentPublisher {
     /**
      * Retrieve the agent metadata from the org after publishing
      *
-     * @param developerName The developer name of the agent
-     * @param originalConnection The original connection to use for retrieval
+     * @param botVersionName The bot version name
+     * @param connection
      */
-    async retrieveAgentMetadata(botVersionName) {
+    async retrieveAgentMetadata(botVersionName, connection) {
         const defaultPackagePath = path.resolve(this.project.getDefaultPackage().path);
         const cs = await source_deploy_retrieve_1.ComponentSetBuilder.build({
             metadata: {
@@ -189,12 +214,12 @@ class AgentPublisher {
                 directoryPaths: [defaultPackagePath],
             },
             org: {
-                username: this.connection.getUsername(),
+                username: this.originalUsername,
                 exclude: [],
             },
         });
         const retrieve = await cs.retrieve({
-            usernameOrConnection: this.connection,
+            usernameOrConnection: connection,
             merge: true,
             format: 'source',
             output: path.resolve(this.project.getPath(), defaultPackagePath),
@@ -215,22 +240,23 @@ class AgentPublisher {
      * 2. Second deployment with target attribute commits the AAB as the published version
      *
      * @param botVersionName The bot version name to use as the target for the final published deployment
+     * @param connection
      * @private
      */
-    async syncAuthoringBundle(botVersionName) {
-        await this.deployAuthoringBundle();
-        await this.deployAuthoringBundle(botVersionName);
+    async syncAuthoringBundle(botVersionName, connection) {
+        await this.deployAuthoringBundle(connection);
+        await this.deployAuthoringBundle(connection, botVersionName);
     }
     /**
      * Deploys the authoring bundle to the Salesforce org after setting the correct target attribute if provided.
      * The target attribute is required for deployment but should not remain in the
      * local source files after deployment.
      *
-     * @param botVersionId The bot version ID used to construct the target attribute
-     *
      * @throws SfError if the deployment fails or if there are component deployment errors
+     * @param botVersionName
+     * @param connection
      */
-    async deployAuthoringBundle(botVersionName) {
+    async deployAuthoringBundle(connection, botVersionName) {
         // 1. if botVersionName is provided, add the target to the local authoring bundle meta.xml file
         // 2. deploy the authoring bundle to the org
         // 3. remove the target from the localauthoring bundle meta.xml file
@@ -251,7 +277,7 @@ class AgentPublisher {
         await (0, promises_1.writeFile)(this.bundleMetaPath, xmlBuilder.build(authoringBundle));
         // 2. attempt to deploy the authoring bundle to the org
         const deploy = await source_deploy_retrieve_1.ComponentSet.fromSource(this.bundleDir).deploy({
-            usernameOrConnection: this.connection.getUsername(),
+            usernameOrConnection: connection,
         });
         const deployResult = await deploy.pollStatus();
         // 3.remove the target from the local authoring bundle meta.xml file
@@ -305,5 +331,5 @@ class AgentPublisher {
         }
     }
 }
-exports.AgentPublisher = AgentPublisher;
-//# sourceMappingURL=agentPublisher.js.map
+exports.ScriptAgentPublisher = ScriptAgentPublisher;
+//# sourceMappingURL=scriptAgentPublisher.js.map

package/lib/agents/scriptAgentPublisher.js.map

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

package/lib/apexUtils.d.ts

@@ -29,6 +29,7 @@ export declare const getDebugLevelId: (connection: Connection) => Promise<string
  * @param userId The user id to create the trace flag for.
  */
 export declare const createTraceFlag: (connection: Connection, userId: string) => Promise<void>;
+export declare function ensureTraceFlag(username: string, connection: Connection): Promise<ApexTraceFlag | undefined>;
 /**
  * Find a trace flag for the given user id.
  *

package/lib/apexUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright 2025, Salesforce, Inc.
+ * 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.
@@ -16,6 +16,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findTraceFlag = exports.createTraceFlag = exports.getDebugLevelId = exports.writeDebugLog = exports.getDebugLog = void 0;
+exports.ensureTraceFlag = ensureTraceFlag;
 const node_path_1 = require("node:path");
 const promises_1 = require("node:fs/promises");
 const core_1 = require("@salesforce/core");
@@ -103,6 +104,15 @@ const createTraceFlag = async (connection, userId) => {
     }
 };
 exports.createTraceFlag = createTraceFlag;
+// once we're previewing agents in the org, with mockActions = false, we'll have to figure out how to get the correct user that was simulated for apex invocattion
+async function ensureTraceFlag(username, connection) {
+    const userId = (await connection.singleRecordQuery(`SELECT Id FROM User WHERE Username = '${username}'`)).Id;
+    const apexTraceFlag = await (0, exports.findTraceFlag)(connection, userId);
+    if (!apexTraceFlag) {
+        await (0, exports.createTraceFlag)(connection, userId);
+    }
+    return apexTraceFlag;
+}
 /**
  * Find a trace flag for the given user id.
  *

package/lib/apexUtils.js.map

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

package/lib/index.d.ts

@@ -1,11 +1,10 @@
-export { type AgentInteractionBase, type BaseAgentConfig, type AgentPreviewStartResponse, type AgentPreviewSendResponse, type AgentPreviewEndResponse, type EndReason, type ApiStatus, type AgentJson, type AgentCompilationSuccess, type AgentScriptContent, type AgentCreateConfig, type AgentCreateResponse, type AgentJobSpec, type AgentJobSpecCreateConfig, type AgentOptions, type AgentTone, type AgentType, type BotMetadata, type BotVersionMetadata, type CompilationError, type DraftAgentTopics, type DraftAgentTopicsBody, type DraftAgentTopicsResponse, type AvailableDefinition, type AgentPreviewMessageLinks, type AgentPreviewMessage, type AgentPreviewError, AgentSource, type ScriptAgent, type PublishedAgent, type AgentTestResultsResponse, type AgentTestStartResponse, type AgentTestStatusResponse, type TestCaseResult, type TestStatus, type AgentTestConfig, type TestCase, type TestSpec, type MetadataMetric, type MetadataExpectation, type MetadataCustomEvaluation, type AiEvaluationDefinition, type AgentTraceResponse, type AgentTraceStep, type UserInputStep, type LLMExecutionStep, type UpdateTopicStep, type EventStep, type ReasoningStep, type PlannerResponseStep, } from './types';
+export { type BaseAgentConfig, type AgentPreviewStartResponse, type AgentPreviewSendResponse, type AgentPreviewEndResponse, type EndReason, type ApiStatus, type AgentJson, type AgentCompilationSuccess, type AgentScriptContent, type AgentCreateConfig, type AgentCreateResponse, type AgentJobSpec, type AgentJobSpecCreateConfig, type AgentOptions, type AgentTone, type AgentType, type BotMetadata, type BotVersionMetadata, type PreviewableAgent, type CompilationError, type DraftAgentTopics, type DraftAgentTopicsBody, type DraftAgentTopicsResponse, type AvailableDefinition, type AgentPreviewMessageLinks, type AgentPreviewMessage, type AgentPreviewError, AgentSource, type ScriptAgentType, type ProductionAgentType, type AgentTestResultsResponse, type AgentTestStartResponse, type AgentTestStatusResponse, type TestCaseResult, type TestStatus, type AgentTestConfig, type TestCase, type TestSpec, type MetadataMetric, type MetadataExpectation, type MetadataCustomEvaluation, type AiEvaluationDefinition, type AgentTraceResponse, type AgentTraceStep, type UserInputStep, type LLMExecutionStep, type UpdateTopicStep, type EventStep, type ReasoningStep, type PlannerResponseStep, } from './types';
 export { metric, findAuthoringBundle, readTranscriptEntries } from './utils';
 export { Agent, AgentCreateLifecycleStages } from './agent';
 export { AgentTester } from './agentTester';
 export { AgentTest, AgentTestCreateLifecycleStages } from './agentTest';
-export { AgentTrace } from './agentTrace';
+export { ProductionAgent } from './agents/productionAgent';
+export { ScriptAgent } from './agents/scriptAgent';
+export { AgentBase, type AgentPreviewInterface } from './agents/agentBase';
 export { convertTestResultsToFormat, humanFriendlyName } from './agentTestResults';
-export { AgentPreview } from './agentPreview';
-export { AgentSimulate } from './agentSimulate';
 export { writeDebugLog } from './apexUtils';
-export { AgentPreviewBase } from './agentPreviewBase';

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright 2025, Salesforce, Inc.
+ * 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.
@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentPreviewBase = exports.writeDebugLog = exports.AgentSimulate = exports.AgentPreview = exports.humanFriendlyName = exports.convertTestResultsToFormat = exports.AgentTrace = exports.AgentTestCreateLifecycleStages = exports.AgentTest = exports.AgentTester = exports.AgentCreateLifecycleStages = exports.Agent = exports.readTranscriptEntries = exports.findAuthoringBundle = exports.metric = exports.AgentSource = void 0;
+exports.writeDebugLog = exports.humanFriendlyName = exports.convertTestResultsToFormat = exports.AgentBase = exports.ScriptAgent = exports.ProductionAgent = exports.AgentTestCreateLifecycleStages = exports.AgentTest = exports.AgentTester = exports.AgentCreateLifecycleStages = exports.Agent = exports.readTranscriptEntries = exports.findAuthoringBundle = exports.metric = exports.AgentSource = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "AgentSource", { enumerable: true, get: function () { return types_1.AgentSource; } });
 var utils_1 = require("./utils");
@@ -30,17 +30,15 @@ Object.defineProperty(exports, "AgentTester", { enumerable: true, get: function
 var agentTest_1 = require("./agentTest");
 Object.defineProperty(exports, "AgentTest", { enumerable: true, get: function () { return agentTest_1.AgentTest; } });
 Object.defineProperty(exports, "AgentTestCreateLifecycleStages", { enumerable: true, get: function () { return agentTest_1.AgentTestCreateLifecycleStages; } });
-var agentTrace_1 = require("./agentTrace");
-Object.defineProperty(exports, "AgentTrace", { enumerable: true, get: function () { return agentTrace_1.AgentTrace; } });
+var productionAgent_1 = require("./agents/productionAgent");
+Object.defineProperty(exports, "ProductionAgent", { enumerable: true, get: function () { return productionAgent_1.ProductionAgent; } });
+var scriptAgent_1 = require("./agents/scriptAgent");
+Object.defineProperty(exports, "ScriptAgent", { enumerable: true, get: function () { return scriptAgent_1.ScriptAgent; } });
+var agentBase_1 = require("./agents/agentBase");
+Object.defineProperty(exports, "AgentBase", { enumerable: true, get: function () { return agentBase_1.AgentBase; } });
 var agentTestResults_1 = require("./agentTestResults");
 Object.defineProperty(exports, "convertTestResultsToFormat", { enumerable: true, get: function () { return agentTestResults_1.convertTestResultsToFormat; } });
 Object.defineProperty(exports, "humanFriendlyName", { enumerable: true, get: function () { return agentTestResults_1.humanFriendlyName; } });
-var agentPreview_1 = require("./agentPreview");
-Object.defineProperty(exports, "AgentPreview", { enumerable: true, get: function () { return agentPreview_1.AgentPreview; } });
-var agentSimulate_1 = require("./agentSimulate");
-Object.defineProperty(exports, "AgentSimulate", { enumerable: true, get: function () { return agentSimulate_1.AgentSimulate; } });
 var apexUtils_1 = require("./apexUtils");
 Object.defineProperty(exports, "writeDebugLog", { enumerable: true, get: function () { return apexUtils_1.writeDebugLog; } });
-var agentPreviewBase_1 = require("./agentPreviewBase");
-Object.defineProperty(exports, "AgentPreviewBase", { enumerable: true, get: function () { return agentPreviewBase_1.AgentPreviewBase; } });
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,iCA4DiB;AA3Bf,oGAAA,WAAW,OAAA;AA6Bb,iCAA6E;AAApE,+FAAA,MAAM,OAAA;AAAE,4GAAA,mBAAmB,OAAA;AAAE,8GAAA,qBAAqB,OAAA;AAC3D,iCAA4D;AAAnD,8FAAA,KAAK,OAAA;AAAE,mHAAA,0BAA0B,OAAA;AAC1C,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,yCAAwE;AAA/D,sGAAA,SAAS,OAAA;AAAE,2HAAA,8BAA8B,OAAA;AAClD,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,uDAAmF;AAA1E,8HAAA,0BAA0B,OAAA;AAAE,qHAAA,iBAAiB,OAAA;AACtD,+CAA8C;AAArC,4GAAA,YAAY,OAAA;AACrB,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,yCAA4C;AAAnC,0GAAA,aAAa,OAAA;AACtB,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAEH,iCA4DiB;AA3Bf,oGAAA,WAAW,OAAA;AA6Bb,iCAA6E;AAApE,+FAAA,MAAM,OAAA;AAAE,4GAAA,mBAAmB,OAAA;AAAE,8GAAA,qBAAqB,OAAA;AAC3D,iCAA4D;AAAnD,8FAAA,KAAK,OAAA;AAAE,mHAAA,0BAA0B,OAAA;AAC1C,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AACpB,yCAAwE;AAA/D,sGAAA,SAAS,OAAA;AAAE,2HAAA,8BAA8B,OAAA;AAClD,4DAA2D;AAAlD,kHAAA,eAAe,OAAA;AACxB,oDAAmD;AAA1C,0GAAA,WAAW,OAAA;AACpB,gDAA2E;AAAlE,sGAAA,SAAS,OAAA;AAClB,uDAAmF;AAA1E,8HAAA,0BAA0B,OAAA;AAAE,qHAAA,iBAAiB,OAAA;AACtD,yCAA4C;AAAnC,0GAAA,aAAa,OAAA"}

package/lib/maybe-mock.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright 2025, Salesforce, Inc.
+ * 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.

package/lib/types.d.ts

@@ -15,13 +15,27 @@ export type BaseAgentConfig = {
 /**
  * Options for creating instances of agents from an org.
  */
-export type AgentOptions = {
+export type AgentOptions = ScriptAgentOptions | ProductionAgentOptions;
+export type ScriptAgentOptions = {
     connection: Connection;
-    project?: SfProject;
-    /**
-     * The API name or ID of the agent (Bot) that exists in the org.
-     */
-    nameOrId: string;
+    project: SfProject;
+    aabDirectory: string;
+};
+export type ProductionAgentOptions = {
+    connection: Connection;
+    project: SfProject;
+    apiNameOrId: string;
+};
+/**
+ * Represents an agent available for preview, either from the org or from a local script file
+ */
+export type PreviewableAgent = {
+    name: string;
+    source: AgentSource;
+    id?: string;
+    developerName?: string;
+    aabDirectory?: string;
+    label?: string;
 };
 export type BotMetadata = {
     Id: string;
@@ -675,12 +689,12 @@ export declare enum AgentSource {
     PUBLISHED = "published",
     SCRIPT = "script"
 }
-export type ScriptAgent = {
+export type ScriptAgentType = {
     DeveloperName: string;
     source: AgentSource.SCRIPT;
     path: string;
 };
-export type PublishedAgent = {
+export type ProductionAgentType = {
     Id: string;
     DeveloperName: string;
     source: AgentSource.PUBLISHED;

package/lib/types.js

@@ -1,6 +1,6 @@
 "use strict";
 /*
- * Copyright 2025, Salesforce, Inc.
+ * 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.

package/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAivBH,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,sCAAuB,CAAA;IACvB,gCAAiB,CAAA;AACnB,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAkwBH,IAAY,WAGX;AAHD,WAAY,WAAW;IACrB,sCAAuB,CAAA;IACvB,gCAAiB,CAAA;AACnB,CAAC,EAHW,WAAW,2BAAX,WAAW,QAGtB"}

package/lib/utils.d.ts

@@ -1,4 +1,5 @@
 import { Connection } from '@salesforce/core';
+import { type PlannerResponse } from './types';
 export declare const metric: readonly ["completeness", "coherence", "conciseness", "output_latency_milliseconds"];
 /**
  * Sanitize a filename by removing or replacing illegal characters.
@@ -42,11 +43,42 @@ export type TranscriptEntry = {
     reason?: string;
 };
 /**
- * Append a transcript entry to the last conversation JSON file under the project local .sfdx folder.
- * If the entry has event: 'start', this will clear the previous conversation and start fresh.
- * Path: <project>/.sfdx/agents/conversations/<agentId>/history.json
+ * Get the session directory path for a specific session
+ */
+export declare const getSessionDir: (agentId: string, sessionId: string) => Promise<string>;
+/**
+ * Copy a directory recursively
+ */
+export declare const copyDirectory: (src: string, dest: string) => Promise<void>;
+/**
+ * Append a transcript entry to the session transcript file
+ */
+export declare const appendTranscriptEntryToSession: (entry: TranscriptEntry, sessionDir: string) => Promise<void>;
+/**
+ * Write a trace to the session traces directory
+ */
+export declare const writeTraceToSession: (planId: string, trace: PlannerResponse | undefined, sessionDir: string) => Promise<void>;
+export declare function getEndpoint(): string;
+/**
+ * Session metadata type
+ */
+export type SessionMetadata = {
+    sessionId: string;
+    agentId: string;
+    startTime: string;
+    endTime?: string;
+    apexDebugging?: boolean;
+    mockMode?: 'Mock' | 'Live Test';
+    planIds: string[];
+};
+/**
+ * Write session metadata to the session directory
+ */
+export declare const writeMetadataToSession: (sessionDir: string, metadata: SessionMetadata) => Promise<void>;
+/**
+ * Update session metadata with end time and plan IDs
  */
-export declare const appendTranscriptEntry: (entry: TranscriptEntry, newSession?: boolean) => Promise<void>;
+export declare const updateMetadataEndTime: (sessionDir: string, endTime: string, planIds: Set<string>) => Promise<void>;
 /**
  * Read and parse the last conversation's transcript entries from JSON.
  * Path: <project>/.sfdx/agents/conversations/<agentId>/history.json