@salesforce/sfdx-agent-sdk 0.1.0

package/dist/agent.js

@@ -0,0 +1,313 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { toHarnessConfig } from './harness/harness-config.js';
+import { DefaultChatSession } from './chat-session.js';
+import { Models } from '@salesforce/llm-gateway-sdk';
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+/**
+ * Default implementation of {@link Agent} that delegates
+ * agent and thread operations to an {@link AgentHarness}.
+ */
+export class DefaultAgent {
+    harness;
+    agentId;
+    projectRoot;
+    config;
+    llmGatewayClient;
+    orgConnection;
+    orgJwt;
+    agentConnectivityResolver;
+    sessions = new Map();
+    sessionSliceUnregisters = new Map();
+    router;
+    telemetryBus = new EventBus();
+    logBus = new LogBus();
+    inboundUnsubs;
+    parentUnsubs;
+    clock;
+    idGenerator;
+    disposed = false;
+    /**
+     * @param harness - The agent harness managing agent and thread lifecycle.
+     * @param agentId - Unique identifier for this agent.
+     * @param projectRoot - Project folder this agent is allowed to operate within.
+     * @param config - Initial agent configuration (instructions, model, tools, etc.).
+     * @param llmGatewayClient - Authenticated LLM gateway client for the resolved org.
+     * @param orgConnection - Authenticated org connection carrying identity and env inference.
+     * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
+     * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param router - Telemetry router used to obtain session slices when sessions are created.
+     * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
+     * @param parent - Manager's bus pair; this agent forwards its events upward into them.
+     */
+    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+        this.harness = harness;
+        this.agentId = agentId;
+        this.projectRoot = projectRoot;
+        this.config = config;
+        this.llmGatewayClient = llmGatewayClient;
+        this.orgConnection = orgConnection;
+        this.orgJwt = orgJwt;
+        this.agentConnectivityResolver = agentConnectivityResolver;
+        this.router = router;
+        this.clock = clock;
+        this.idGenerator = idGenerator;
+        this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
+        this.parentUnsubs = [this.telemetryBus.forwardTo(parent.telemetry), this.logBus.forwardTo(parent.log)];
+    }
+    /**
+     * @requirements
+     * - MUST return the agent's ID.
+     */
+    getId() {
+        this.assertNotDisposed();
+        return this.agentId;
+    }
+    /** Returns the project root folder this agent operates within. */
+    getProjectRoot() {
+        this.assertNotDisposed();
+        return this.projectRoot;
+    }
+    getOrgConnection() {
+        this.assertNotDisposed();
+        return this.orgConnection;
+    }
+    /**
+     * @requirements
+     * - MUST return a shallow copy of the internal `config` object to prevent external mutation of the agent's state.
+     */
+    getAgentConfig() {
+        this.assertNotDisposed();
+        return { ...this.config };
+    }
+    getMcpServerInfo() {
+        this.assertNotDisposed();
+        return this.harness.getMcpServerInfo(this.agentId);
+    }
+    /**
+     * @requirements
+     * - MUST merge the provided `config` with the internal `config` object.
+     * - MUST guarantee that the `agentId` remains unchanged during the merge.
+     * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
+     * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
+     * - MUST preserve the previous in-memory config state if recreation fails.
+     */
+    async updateAgentConfig(config = {}, options) {
+        this.assertNotDisposed();
+        const previousConfig = { ...this.config };
+        const previousClient = this.llmGatewayClient;
+        const previousOrgJwt = this.orgJwt;
+        const nextConfig = { ...this.config, ...config };
+        const orgAliasRequested = Object.prototype.hasOwnProperty.call(config, 'orgAlias');
+        const previousModelName = previousClient.getModel().name;
+        const nextModelName = nextConfig.modelId ?? Models.getDefault().name;
+        let nextClient = previousClient;
+        let nextConnection = this.orgConnection;
+        let nextOrgJwt = this.orgJwt;
+        if (orgAliasRequested) {
+            const runtime = await this.agentConnectivityResolver.resolve(this.projectRoot, nextConfig);
+            nextClient = runtime.llmGatewayClient;
+            nextConnection = runtime.orgConnection;
+            nextOrgJwt = runtime.orgJwt;
+        }
+        else if (nextModelName !== previousModelName) {
+            // Keep the same authenticated client, but pin the updated model.
+            // (If modelId is omitted, the resolver pinned the default at creation time.)
+            nextClient.setModel(Models.getByName(nextModelName));
+        }
+        await this.harness.destroyAgent(this.agentId);
+        try {
+            await this.harness.createAgent(this.agentId, this.projectRoot, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), options);
+            this.config = nextConfig;
+            this.llmGatewayClient = nextClient;
+            this.orgConnection = nextConnection;
+            this.orgJwt = nextOrgJwt;
+            // Release the old client only once the swap has succeeded. When the orgAlias is unchanged,
+            // nextClient === previousClient and we must NOT dispose.
+            if (nextClient !== previousClient) {
+                previousClient.dispose();
+            }
+        }
+        catch (error) {
+            // Best-effort restoration to keep wrapper and harness state aligned.
+            try {
+                // Restore client model if we mutated it in-place.
+                if (nextClient === previousClient) {
+                    previousClient.setModel(Models.getByName(previousModelName));
+                }
+                await this.harness.createAgent(this.agentId, this.projectRoot, previousClient, toHarnessConfig(previousConfig, previousOrgJwt));
+            }
+            catch {
+                // Ignore restoration errors; rethrow the original failure.
+            }
+            // A freshly-resolved client we never installed must be released so its auth resources don't leak.
+            if (nextClient !== previousClient) {
+                try {
+                    nextClient.dispose();
+                }
+                catch {
+                    // Ignore; the original error is the one the caller cares about.
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.createThread(this.config.agentId)` to generate a new thread ID.
+     * - MUST instantiate a new `DefaultChatSession` initialized with the harness, agent ID, and the new thread ID.
+     * - MUST store the newly created session in the internal `sessions` map, keyed by the thread ID.
+     * - MUST return the newly created session.
+     */
+    async createChatSession() {
+        this.assertNotDisposed();
+        const threadId = await this.harness.createThread(this.agentId);
+        return this.attachSession(threadId);
+    }
+    /**
+     * @requirements
+     * - MUST throw an Error if the provided `sessionId` is not found in the internal `sessions` map.
+     * - MUST delegate to `this.harness.destroyThread(this.config.agentId, sessionId)`.
+     * - MUST remove the session from the internal `sessions` map.
+     */
+    async destroyChatSession(sessionId) {
+        this.assertNotDisposed();
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new AgentSDKError(`No ChatSession found with id: "${sessionId}"`, AgentSDKErrorType.CHAT_SESSION_NOT_FOUND);
+        }
+        await this.harness.destroyThread(this.agentId, sessionId);
+        this.detachSession(sessionId, session);
+    }
+    /**
+     * @requirements
+     * - MUST throw an Error if the provided `sessionId` is not found in the internal `sessions` map.
+     * - MUST return the session object associated with the given `sessionId`.
+     */
+    getChatSession(sessionId) {
+        this.assertNotDisposed();
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            throw new AgentSDKError(`No ChatSession found with id: "${sessionId}"`, AgentSDKErrorType.CHAT_SESSION_NOT_FOUND);
+        }
+        return session;
+    }
+    /**
+     * @requirements
+     * - MUST return an array of all string keys (session IDs) currently tracked in the internal `sessions` map.
+     */
+    getChatSessionIds() {
+        this.assertNotDisposed();
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * @requirements
+     * - MUST throw an Error if the provided `sourceSessionId` is not found in the internal `sessions` map.
+     * - MUST delegate to `this.harness.cloneThread(this.config.agentId, sourceSessionId)` to create a new thread with cloned history.
+     * - MUST instantiate a new `DefaultChatSession` initialized with the harness, agent ID, and the new thread ID.
+     * - MUST store the newly created session in the internal `sessions` map, keyed by the new thread ID.
+     * - MUST return the newly created session.
+     */
+    async cloneChatSession(sourceSessionId) {
+        this.assertNotDisposed();
+        if (!this.sessions.has(sourceSessionId)) {
+            throw new AgentSDKError(`No ChatSession found with id: "${sourceSessionId}"`, AgentSDKErrorType.CHAT_SESSION_NOT_FOUND);
+        }
+        const newThreadId = await this.harness.cloneThread(this.agentId, sourceSessionId);
+        return this.attachSession(newThreadId);
+    }
+    /**
+     * @requirements
+     * - MUST throw an Error if the provided `sessionId` is not found in the internal `sessions` map.
+     * - MUST delegate to `this.harness.compactThread(this.agentId, sessionId)` to create a new thread with a summary.
+     * - MUST detach the source session from this agent on success — the
+     *   harness destroys the source thread, so leaving the wrapper attached
+     *   would leak a router slice and a `DefaultChatSession` whose thread
+     *   no longer exists.
+     * - MUST instantiate a new `DefaultChatSession` initialized with the harness, agent ID, and the new thread ID.
+     * - MUST store the newly created session in the internal `sessions` map, keyed by the new thread ID.
+     * - MUST return the newly created session.
+     */
+    async compactChatSession(sessionId) {
+        this.assertNotDisposed();
+        const sourceSession = this.sessions.get(sessionId);
+        if (!sourceSession) {
+            throw new AgentSDKError(`No ChatSession found with id: "${sessionId}"`, AgentSDKErrorType.CHAT_SESSION_NOT_FOUND);
+        }
+        const newThreadId = await this.harness.compactThread(this.agentId, sessionId);
+        this.detachSession(sessionId, sourceSession);
+        return this.attachSession(newThreadId);
+    }
+    /**
+     * @requirements
+     * - MUST iterate over all active session IDs and sequentially delegate to `this.harness.destroyThread()` for each.
+     * - MUST clear the internal `sessions` map.
+     * - MUST delegate to `this.harness.destroyAgent(this.config.agentId)` to clean up the agent's harness resources.
+     */
+    async destroy() {
+        if (this.disposed) {
+            return;
+        }
+        for (const [sessionId, session] of this.sessions) {
+            await this.harness.destroyThread(this.agentId, sessionId);
+            this.detachSession(sessionId, session);
+        }
+        this.sessions.clear();
+        await this.harness.destroyAgent(this.agentId);
+        this.llmGatewayClient.dispose();
+        this.telemetryBus.emit({
+            type: 'agent-destroyed',
+            timestamp: this.clock.now(),
+            agentId: this.agentId,
+        });
+        for (const unsub of this.inboundUnsubs)
+            unsub();
+        for (const unsub of this.parentUnsubs)
+            unsub();
+        this.telemetryBus.dispose();
+        this.logBus.dispose();
+        this.disposed = true;
+    }
+    onTelemetry(callback) {
+        this.assertNotDisposed();
+        return this.telemetryBus.on(callback);
+    }
+    onLog(callback) {
+        this.assertNotDisposed();
+        return this.logBus.on(callback);
+    }
+    attachSession(threadId) {
+        const slice = this.router.registerSession(threadId);
+        const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {
+            telemetry: this.telemetryBus,
+            log: this.logBus,
+        }, this.clock, this.idGenerator);
+        this.sessions.set(threadId, session);
+        this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
+        this.telemetryBus.emit({
+            type: 'session-created',
+            timestamp: this.clock.now(),
+            agentId: this.agentId,
+            threadId,
+        });
+        return session;
+    }
+    detachSession(threadId, session) {
+        session.dispose();
+        const unregister = this.sessionSliceUnregisters.get(threadId);
+        if (unregister) {
+            unregister();
+            this.sessionSliceUnregisters.delete(threadId);
+        }
+        this.sessions.delete(threadId);
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new AgentSDKError('Agent has been disposed.', AgentSDKErrorType.DISPOSED);
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEH,QAAQ,EACR,MAAM,EAGN,SAAS,EAGT,aAAa,GAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAoB,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAoB,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,MAAM,EAA4C,MAAM,6BAA6B,CAAC;AAE/F,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAwG/D;;;GAGG;AACH,MAAM,OAAO,YAAY;IACJ,OAAO,CAAe;IACtB,OAAO,CAAS;IAChB,WAAW,CAAS;IAC7B,MAAM,CAAc;IACpB,gBAAgB,CAAmB;IACnC,aAAa,CAAgB;IAC7B,MAAM,CAAe;IACZ,yBAAyB,CAA4B;IACrD,QAAQ,GAAoC,IAAI,GAAG,EAAE,CAAC;IACtD,uBAAuB,GAA4B,IAAI,GAAG,EAAE,CAAC;IAC7D,MAAM,CAAkB;IACxB,YAAY,GAAiB,IAAI,QAAQ,EAAkB,CAAC;IAC5D,MAAM,GAAW,IAAI,MAAM,EAAE,CAAC;IAC9B,aAAa,CAAgB;IAC7B,YAAY,CAAgB;IAC5B,KAAK,CAAQ;IACb,WAAW,CAAoB;IACxC,QAAQ,GAAY,KAAK,CAAC;IAElC;;;;;;;;;;;;OAYG;IACH,YACI,OAAqB,EACrB,OAAe,EACf,WAAmB,EACnB,MAAmB,EACnB,gBAAkC,EAClC,aAA4B,EAC5B,MAAoB,EACpB,yBAAoD,EACpD,MAAuB,EACvB,OAAuB,EACvB,MAAwB,EACxB,QAAe,IAAI,SAAS,EAAE,EAC9B,cAAiC,IAAI,aAAa,EAAE;QAEpD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,yBAAyB,GAAG,yBAAyB,CAAC;QAC3D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,aAAa,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1G,IAAI,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3G,CAAC;IAED;;;OAGG;IACH,KAAK;QACD,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,kEAAkE;IAClE,cAAc;QACV,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;IAED,gBAAgB;QACZ,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,aAAa,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACH,cAAc;QACV,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED,gBAAgB;QACZ,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,iBAAiB,CAAC,SAAsB,EAAE,EAAE,OAAuC;QACrF,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,cAAc,GAAgB,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvD,MAAM,cAAc,GAAG,IAAI,CAAC,gBAAgB,CAAC;QAC7C,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC;QACnC,MAAM,UAAU,GAAgB,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;QAE9D,MAAM,iBAAiB,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACnF,MAAM,iBAAiB,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC;QACzD,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC;QAErE,IAAI,UAAU,GAAqB,cAAc,CAAC;QAClD,IAAI,cAAc,GAAkB,IAAI,CAAC,aAAa,CAAC;QACvD,IAAI,UAAU,GAAiB,IAAI,CAAC,MAAM,CAAC;QAE3C,IAAI,iBAAiB,EAAE,CAAC;YACpB,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC;YAC3F,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;YACtC,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YACvC,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;QAChC,CAAC;aAAM,IAAI,aAAa,KAAK,iBAAiB,EAAE,CAAC;YAC7C,iEAAiE;YACjE,6EAA6E;YAC7E,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC;YACD,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAC1B,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,WAAW,EAChB,UAAU,EACV,eAAe,CAAC,UAAU,EAAE,UAAU,CAAC,EACvC,OAAO,CACV,CAAC;YACF,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;YACzB,IAAI,CAAC,gBAAgB,GAAG,UAAU,CAAC;YACnC,IAAI,CAAC,aAAa,GAAG,cAAc,CAAC;YACpC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC;YACzB,2FAA2F;YAC3F,yDAAyD;YACzD,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;gBAChC,cAAc,CAAC,OAAO,EAAE,CAAC;YAC7B,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACb,qEAAqE;YACrE,IAAI,CAAC;gBACD,kDAAkD;gBAClD,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;oBAChC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;gBACjE,CAAC;gBAED,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAC1B,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,WAAW,EAChB,cAAc,EACd,eAAe,CAAC,cAAc,EAAE,cAAc,CAAC,CAClD,CAAC;YACN,CAAC;YAAC,MAAM,CAAC;gBACL,2DAA2D;YAC/D,CAAC;YACD,kGAAkG;YAClG,IAAI,UAAU,KAAK,cAAc,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACD,UAAU,CAAC,OAAO,EAAE,CAAC;gBACzB,CAAC;gBAAC,MAAM,CAAC;oBACL,gEAAgE;gBACpE,CAAC;YACL,CAAC;YACD,MAAM,KAAK,CAAC;QAChB,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,iBAAiB;QACnB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACtC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,MAAM,IAAI,aAAa,CACnB,kCAAkC,SAAS,GAAG,EAC9C,iBAAiB,CAAC,sBAAsB,CAC3C,CAAC;QACN,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1D,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,cAAc,CAAC,SAAiB;QAC5B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,MAAM,IAAI,aAAa,CACnB,kCAAkC,SAAS,GAAG,EAC9C,iBAAiB,CAAC,sBAAsB,CAC3C,CAAC;QACN,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,iBAAiB;QACb,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,gBAAgB,CAAC,eAAuB;QAC1C,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,aAAa,CACnB,kCAAkC,eAAe,GAAG,EACpD,iBAAiB,CAAC,sBAAsB,CAC3C,CAAC;QACN,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAClF,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACtC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,MAAM,IAAI,aAAa,CACnB,kCAAkC,SAAS,GAAG,EAC9C,iBAAiB,CAAC,sBAAsB,CAC3C,CAAC;QACN,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC9E,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;IAC3C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACT,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,KAAK,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC/C,MAAM,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;YAC1D,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QACtB,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAEhC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,iBAAiB;YACvB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;SACxB,CAAC,CAAC;QAEH,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,aAAa;YAAE,KAAK,EAAE,CAAC;QAChD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,YAAY;YAAE,KAAK,EAAE,CAAC;QAC/C,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACzB,CAAC;IAED,WAAW,CAAC,QAAgC;QACxC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,KAAK,CAAC,QAAqC;QACvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAEO,aAAa,CAAC,QAAgB;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAClC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,OAAO,EACZ,QAAQ,EACR,KAAK,EACL;YACI,SAAS,EAAE,IAAI,CAAC,YAAY;YAC5B,GAAG,EAAE,IAAI,CAAC,MAAM;SACnB,EACD,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,WAAW,CACnB,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC1F,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,iBAAiB;YACvB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ;SACX,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACnB,CAAC;IAEO,aAAa,CAAC,QAAgB,EAAE,OAA2B;QAC/D,OAAO,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,UAAU,GAAG,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC9D,IAAI,UAAU,EAAE,CAAC;YACb,UAAU,EAAE,CAAC;YACb,IAAI,CAAC,uBAAuB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;IAEO,iBAAiB;QACrB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CAAC,0BAA0B,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QACpF,CAAC;IACL,CAAC;CACJ"}

package/dist/chat-session.d.ts

@@ -0,0 +1,298 @@
+import { type Clock, LogBus, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
+import type { AgentHarness } from './harness/agent-harness.js';
+import type { StreamOptions } from './harness/harness-config.js';
+import type { TelemetrySlice } from './internal/telemetry-router.js';
+import type { ChatEvent, ChatStreamResult } from './types/events.js';
+import type { Message } from './types/messages.js';
+import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
+import type { ToolResultInfo } from './types/tools.js';
+/**
+ * Options for a single chat interaction.
+ */
+export type ChatOptions = StreamOptions;
+/**
+ * Parent bus pair used to wire upward forwarding at construction time.
+ */
+export type ChatSessionParentBuses = {
+    telemetry: TelemetryBus;
+    log: LogBus;
+};
+/**
+ * An isolated conversation thread with an agent.
+ *
+ * Each `ChatSession` maps to a single thread in the underlying harness. Sessions maintain their own message
+ * history but share the parent agent's tools, workspace, and model configuration.
+ *
+ * ### Failure handling for streaming methods
+ *
+ * `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToolCall()` share a single failure
+ * contract. Subscribers registered via {@link ChatSession.subscribe} are guaranteed to observe a
+ * terminal event for every turn:
+ *
+ * - **Pre-stream failure** (the harness rejects before producing a stream): subscribers receive an
+ *   `ErrorEvent` followed by a `FinishEvent` with `finishReason: 'error'`, then the returned promise
+ *   rejects with the original error.
+ * - **In-stream failure** (the stream yields an `error` event or the underlying generator throws):
+ *   the event stream itself yields the `ErrorEvent` (synthesizing one from a thrown exception if
+ *   needed) and, if no `FinishEvent` was already emitted, appends a synthetic
+ *   `FinishEvent(finishReason: 'error')` at the end. Subscribers see the same sequence.
+ * - **Calling a disposed session** throws `AgentSDKError('DISPOSED')` synchronously without
+ *   notifying subscribers — this is a programmer error, not an operational one.
+ */
+export interface ChatSession {
+    /** Returns the unique session/thread identifier. */
+    getId(): string;
+    /**
+     * Send a message and stream the agent's response.
+     * Returns a {@link ChatStreamResult} which provides multiple ways to consume
+     * the stream (text-only or full events).
+     *
+     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
+     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     *
+     * @param message - User message as a plain string.
+     * @param options - Per-call options controlling mode, tools, model, etc.
+     */
+    chat(message: string, options?: ChatOptions): Promise<ChatStreamResult>;
+    /**
+     * Feed the result of a client-side tool execution back into the conversation
+     * and resume stream generation.
+     *
+     * Resumes the suspended agentic loop from the most recent `chat()` call.
+     *
+     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
+     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     *
+     * @param toolResult - The completed tool execution result.
+     */
+    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    /**
+     * Approve a pending tool call, allowing the harness to execute it.
+     * Called after receiving a `tool-approval-request` event from the stream.
+     *
+     * Returns a `ChatStreamResult` containing the continuation stream — the harness
+     * executes the approved tool, generates the model's follow-up response, and
+     * streams both the text and events back to the caller.
+     *
+     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
+     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     *
+     * @param toolCallId - ID of the pending tool call to approve.
+     * @param options - Optional approval metadata.
+     * @param options.remember - When `true`, signals that the consumer wants to
+     *   persist this approval decision (e.g., "always allow this tool").
+     *   The harness does not implement the persistence — the consumer manages
+     *   its own permission cache. Borrowed from OpenCode's `once/always/reject` model.
+     */
+    approveToolCall(toolCallId: string, options?: {
+        remember?: boolean;
+    }): Promise<ChatStreamResult>;
+    /**
+     * Decline a pending tool call. The stream resumes with the model
+     * acknowledging the decline and potentially suggesting alternatives.
+     *
+     * Returns a `ChatStreamResult` containing the continuation stream — the harness
+     * cancels the pending tool call, generates the model's acknowledgement response,
+     * and streams both the text and events back to the caller.
+     *
+     * On pre-stream failure, subscribers are notified with `ErrorEvent` + `FinishEvent` before
+     * the returned promise rejects. See the interface-level "Failure handling" notes for details.
+     *
+     * @param toolCallId - ID of the pending tool call to decline.
+     */
+    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * Retrieve message history for this session.
+     *
+     * @returns All messages in chronological order (ascending by creation time).
+     */
+    getMessageHistory(): Promise<Message[]>;
+    /** Delete all messages in this session's history. */
+    clearHistory(): Promise<void>;
+    /**
+     * Inject context messages into the thread without triggering an LLM response.
+     * Useful for seeding file contents, system instructions, or prior conversation
+     * state before the user's first prompt.
+     *
+     * Borrowed from OpenCode's `session.prompt({ noReply: true })` pattern.
+     *
+     * @param message - Context to inject (string shorthand or structured messages).
+     */
+    addContext(message: string | Message[]): Promise<void>;
+    /**
+     * Register a callback to receive chat events in real-time. Returns an `Unsubscribe` function
+     * that removes the listener. The returned function is safe to call after `dispose()` (no-op).
+     * Multiple listeners can be registered concurrently.
+     */
+    subscribe(callback: (event: ChatEvent) => void): Unsubscribe;
+    /** Subscribe to telemetry events scoped to this session. Returns an unsubscribe function. */
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    /** Subscribe to structured log records scoped to this session. Returns an unsubscribe function. */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    /**
+     * Release session-level event resources. Idempotent. After `dispose()`, public methods throw
+     * `AgentSDKError('DISPOSED')`.
+     */
+    dispose(): void;
+}
+/**
+ * Default implementation of {@link ChatSession} that delegates all operations
+ * to an {@link AgentHarness}. The session holds its agent ID and thread ID
+ * and forwards calls with appropriate scoping.
+ */
+export declare class DefaultChatSession implements ChatSession {
+    private readonly harness;
+    private readonly agentId;
+    private readonly threadId;
+    private readonly chatEventBus;
+    private readonly telemetryBus;
+    private readonly logBus;
+    private readonly inboundUnsubs;
+    private readonly parentUnsubs;
+    private readonly clock;
+    private readonly idGenerator;
+    private disposed;
+    /**
+     * @param harness - The agent harness managing thread and message lifecycle.
+     * @param agentId - ID of the agent this session belongs to.
+     * @param threadId - ID of the conversation thread backing this session.
+     * @param inbound - Router slice delivering harness events routed to this session.
+     * @param parent - Parent agent's buses; this session forwards its events upward into them.
+     * @param clock - Source of monotonic timestamps for telemetry events. Defaults to `RealClock`.
+     * @param idGenerator - Source of message ids for `addContext()`. Defaults to `UUIDGenerator`.
+     */
+    constructor(harness: AgentHarness, agentId: string, threadId: string, inbound: TelemetrySlice, parent: ChatSessionParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    getId(): string;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.stream()`, passing `this.agentId` and `this.threadId`.
+     * - MUST pass the `message` string and `options` arguments directly to the harness.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    chat(message: string, options?: ChatOptions): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.submitToolResult()`, passing `this.agentId` and `this.threadId`.
+     * - MUST pass the `toolResult` argument directly to the harness.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    submitToolResult(toolResult: ToolResultInfo): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST yield each event from the provided `stream`.
+     * - MUST emit the event to the internal `chatEventBus`.
+     * - MUST always yield a `FinishEvent` with `finishReason: 'error'` after any error path
+     *   (in-stream `ErrorEvent` or thrown exception) if no `FinishEvent` was already emitted.
+     * - MUST emit `chat-stream-completed` telemetry on natural completion (no error path).
+     * - MUST emit `chat-stream-error` telemetry exactly once when an error occurred (in-stream
+     *   `ErrorEvent` or thrown exception). Mutually exclusive with `chat-stream-completed`.
+     * - MUST derive `tool-execution-started`, `tool-execution-completed`, and
+     *   `tool-approval-requested` telemetry from the corresponding `ChatEvent` types so harness
+     *   implementations don't reimplement this. `tool-execution-completed.durationMs` is measured
+     *   between the matching `tool-call` and `tool-result`; an unmatched `tool-result` (e.g. from
+     *   a resume flow that crosses a stream boundary) is skipped.
+     *
+     * `chat-stream-started` is emitted by the entry-point method (chat / submitToolResult /
+     * approveToolCall / declineToolCall) before the harness call so that pre-stream rejections
+     * still produce a started+error pair. `startedAt` is captured there and threaded down so
+     * `durationMs` measures real elapsed time on both terminal events.
+     */
+    private wrapEventStream;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.approveToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST emit `tool-approval-resolved` telemetry with `approved: true` only after the harness
+     *   call resolves. Pre-stream rejections produce `chat-stream-error` via `notifyPreStreamError`
+     *   and intentionally skip approval-resolved emission — consumers correlate the prior
+     *   `tool-approval-requested` by `toolCallId` and observe the failure on the chat-stream contract.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     * - The `options.remember` flag is consumer-only metadata — the harness does not use it.
+     */
+    approveToolCall(toolCallId: string, _options?: {
+        remember?: boolean;
+    }): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.declineToolCall()`, passing `this.agentId`, `this.threadId`, and `toolCallId`.
+     * - MUST wrap the returned `eventStream` using `this.wrapEventStream()` so that listeners are notified.
+     * - MUST return an object containing the original `textStream` and the wrapped `eventStream`.
+     * - MUST emit `tool-approval-resolved` telemetry with `approved: false` only after the harness
+     *   call resolves. Pre-stream rejections produce `chat-stream-error` via `notifyPreStreamError`
+     *   and intentionally skip approval-resolved emission.
+     * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
+     *   before returning a stream result.
+     */
+    declineToolCall(toolCallId: string): Promise<ChatStreamResult>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
+     * - MUST return the result directly.
+     */
+    getMessageHistory(): Promise<Message[]>;
+    /**
+     * @requirements
+     * - MUST delegate to `this.harness.clearMessages()`, passing `this.agentId` and `this.threadId`.
+     */
+    clearHistory(): Promise<void>;
+    /**
+     * @requirements
+     * - IF `message` is a `string`, it MUST be formatted into a standard `Message` object array containing exactly one message.
+     * - The formatted message MUST have `role: 'user'`.
+     * - The formatted message MUST have a newly generated `id` from the injected `idGenerator`.
+     * - The formatted message MUST have a `createdAt` timestamp from the injected `clock`.
+     * - IF `message` is already an array of `Message` objects, it MUST be used directly.
+     * - MUST delegate the final array of messages to `this.harness.addContext()`, passing `this.agentId` and `this.threadId`.
+     */
+    addContext(message: string | Message[]): Promise<void>;
+    /**
+     * @requirements
+     * - MUST register the provided `callback` on the internal `chatEventBus`.
+     * - MUST return an `Unsubscribe` closure that removes the callback when called.
+     */
+    subscribe(callback: (event: ChatEvent) => void): Unsubscribe;
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    dispose(): void;
+    private emitToolApprovalResolved;
+    /**
+     * Derives `tool-execution-*` and `tool-approval-requested` telemetry from `ChatEvent`s as
+     * they pass through the stream wrapper. Centralizing the derivation here keeps every harness
+     * implementation free of telemetry plumbing — they just yield the right `ChatEvent` shapes.
+     *
+     * `tool-execution-completed.durationMs` is measured between the matching `tool-call` and
+     * `tool-result` using `this.clock`. An unmatched `tool-result` (e.g. a resume flow that
+     * crosses a stream boundary so the original `tool-call` was on a previous stream) is skipped
+     * — the consumer correlates by `toolCallId` against the earlier `tool-execution-started`.
+     */
+    private deriveToolTelemetry;
+    /**
+     * Emits a `chat-stream-started` telemetry event and returns the `startedAt` timestamp the
+     * caller threads through to the stream wrapper / pre-stream error notifier so terminal
+     * events report real elapsed time.
+     *
+     * Hoisting this above the harness call keeps the `chat-stream-*` contract honest under
+     * pre-stream failures: every `chat-stream-error` follows a `chat-stream-started` for the
+     * same `(agentId, threadId)` pair.
+     */
+    private emitChatStreamStarted;
+    /**
+     * Emits an `ErrorEvent` + `FinishEvent` to all `subscribe()` listeners and a `chat-stream-error`
+     * telemetry event for a failure that occurred before a stream was established. The caller is
+     * responsible for re-throwing the original error after calling this — the method itself does
+     * not throw.
+     *
+     * `startedAt` is the timestamp captured by {@link emitChatStreamStarted} so `durationMs`
+     * measures real elapsed time even for pre-stream rejections.
+     */
+    private notifyPreStreamError;
+    private assertNotDisposed;
+}