@salesforce/sfdx-agent-sdk 0.1.0

package/dist/agent-manager.d.ts

@@ -0,0 +1,134 @@
+import { type Clock, LogBus, type LogRecord, type Unsubscribe, type UniqueIDGenerator } from '@salesforce/agentic-common';
+import { type AgentHarness } from './harness/agent-harness.js';
+import type { HarnessFactory } from './harness/harness-factory.js';
+import { type AgentConfig } from './harness/harness-config.js';
+import { type Agent } from './agent.js';
+import type { TelemetryEventCallback } from './types/telemetry-events.js';
+import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+/**
+ * Manages the lifecycle of {@link Agent} instances.
+ *
+ * The manager owns an {@link AgentHarness} and coordinates initialization,
+ * agent creation, and graceful shutdown. The harness implementation is
+ * abstracted away from downstream code (agents, sessions).
+ *
+ * ### Persistence Responsibility
+ * Persistence is shared between the harness and the consuming application:
+ * - **Engine**: Handles physical data persistence (database storage of threads, messages, and memory state).
+ * - **Application**: Handles lifecycle persistence. It manages the discovery and restoration of saved agents,
+ *   and calls `createAgent(projectRoot, { agentId: savedId, ...savedConfig })` to rebuild active agent state in memory
+ *   (like MCP connections and custom tool closures) while reconnecting to the persistent memory data.
+ */
+export declare class AgentManager {
+    private readonly harness;
+    private readonly agentIdGenerator;
+    private readonly agentConnectivityResolver;
+    private readonly clock;
+    private readonly agents;
+    private readonly telemetryBus;
+    private readonly logBus;
+    private readonly router;
+    private readonly unroutedUnsubs;
+    private disposed;
+    /**
+     * Creates a new {@link AgentManager}.
+     *
+     * This constructor is **exposed for testing only** so unit tests can inject a stubbed
+     * {@link AgentHarness} and deterministic ID generator.
+     *
+     * Production callers should use {@link createAgentManager} instead.
+     *
+     * @example
+     * ```ts
+     * // Recommended for production usage (constructs the default connectivity resolver):
+     * const manager = await createAgentManager(storageRootFolder, harnessFactory);
+     * ```
+     */
+    constructor(harness: AgentHarness, agentConnectivityResolver: AgentConnectivityResolver, agentIdGenerator?: UniqueIDGenerator, clock?: Clock, logBus?: LogBus);
+    /**
+     * Shuts down the harness and destroys all managed agents.
+     *
+     * @requirements
+     * - MUST iterate through all agents in the internal `agents` map and call `agent.destroy()` on each.
+     * - MUST clear the internal `agents` map.
+     * - MUST delegate to `this.harness.shutdown()` to release harness-level resources.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Creates a new `Agent` with the given configuration.
+     *
+     * @param projectRoot - Absolute path to the project folder the agent can manipulate files from.
+     *   Relative paths are resolved against `process.cwd()`. The path must exist and be a directory.
+     * @param config - Agent configuration (instructions, tools, model, etc.).
+     * @param options - Optional execution options, including abort signals.
+     * @returns A new `Agent` ready for chat sessions.
+     *
+     * @throws If `projectRoot` does not exist or is not a directory.
+     *
+     * @requirements
+     * - MUST resolve `projectRoot` to an absolute, normalized path before use.
+     * - MUST throw an Error if the resolved `projectRoot` does not exist or is not a directory.
+     * - MUST throw an Error if `config.agentId` is provided and an agent with that ID already exists in the internal `agents` map.
+     * - MUST generate a unique ID via `this.agentIdGenerator` if `config.agentId` is omitted.
+     * - MUST delegate to `this.harness.createAgent(agentId, projectRoot, llmGatewayClient, config, options)` to register the agent in the harness and allow for cancellation.
+     * - MUST instantiate a `DefaultAgent` with the harness and the complete configuration.
+     * - MUST store the newly created agent in the internal `agents` map, keyed by its `agentId`.
+     * - MUST return the newly created agent.
+     */
+    createAgent(projectRoot: string, config?: AgentConfig & {
+        agentId?: string;
+    }, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<Agent>;
+    /**
+     * Returns the IDs of all currently managed agents.
+     *
+     * @requirements
+     * - MUST return an array of all string keys (agent IDs) currently tracked in the internal `agents` map.
+     */
+    getAgentIds(): string[];
+    /**
+     * Retrieves a managed agent by its ID.
+     *
+     * @param agentId - ID of the agent to retrieve.
+     *
+     * @requirements
+     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
+     * - MUST return the `Agent` instance associated with the given `agentId`.
+     */
+    getAgent(agentId: string): Agent;
+    /**
+     * Destroys a managed agent by its ID, releasing all its resources.
+     *
+     * @param agentId - ID of the agent to destroy.
+     *
+     * @requirements
+     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
+     * - MUST call `destroy()` on the target agent instance.
+     * - MUST remove the agent from the internal `agents` map.
+     */
+    destroyAgent(agentId: string): Promise<void>;
+    /** Subscribe to telemetry events across every managed agent. Returns an unsubscribe function. */
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    /** Subscribe to structured log records across every managed agent. Returns an unsubscribe function. */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    private assertNotDisposed;
+}
+/**
+ * Creates an {@link AgentManager} using the provided harness factory.
+ *
+ * Use this function in production code. It validates the `storageRootFolder`,
+ * verifies the factory advertises a supported protocol version (failing fast
+ * before any expensive harness construction), constructs the harness
+ * asynchronously, sanity-checks that the constructed harness honors the
+ * factory's advertised version, and returns a ready-to-use manager.
+ *
+ * @param storageRootFolder - Existing directory used for agent persistence.
+ * @param harnessFactory - Factory that constructs the harness implementation.
+ *
+ * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
+ *   the constructed harness reports a `protocolVersion` outside
+ *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
+ *   version disagrees with the factory's.
+ */
+export declare function createAgentManager(storageRootFolder: string, harnessFactory: HarnessFactory): Promise<AgentManager>;

package/dist/agent-manager.js

@@ -0,0 +1,266 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { EventBus, LogBus, RealClock, UUIDGenerator, } from '@salesforce/agentic-common';
+import { resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { SUPPORTED_PROTOCOL_VERSIONS } from './harness/agent-harness.js';
+import { toHarnessConfig } from './harness/harness-config.js';
+import { DefaultAgent } from './agent.js';
+import { AgentSDKError, AgentSDKErrorType } from './errors.js';
+import { TelemetryRouter } from './internal/telemetry-router.js';
+import { DefaultAgentConnectivityResolver } from './agent-connectivity-resolver.js';
+/**
+ * Manages the lifecycle of {@link Agent} instances.
+ *
+ * The manager owns an {@link AgentHarness} and coordinates initialization,
+ * agent creation, and graceful shutdown. The harness implementation is
+ * abstracted away from downstream code (agents, sessions).
+ *
+ * ### Persistence Responsibility
+ * Persistence is shared between the harness and the consuming application:
+ * - **Engine**: Handles physical data persistence (database storage of threads, messages, and memory state).
+ * - **Application**: Handles lifecycle persistence. It manages the discovery and restoration of saved agents,
+ *   and calls `createAgent(projectRoot, { agentId: savedId, ...savedConfig })` to rebuild active agent state in memory
+ *   (like MCP connections and custom tool closures) while reconnecting to the persistent memory data.
+ */
+export class AgentManager {
+    harness;
+    agentIdGenerator;
+    agentConnectivityResolver;
+    clock;
+    agents = new Map();
+    telemetryBus = new EventBus();
+    logBus;
+    router;
+    unroutedUnsubs;
+    disposed = false;
+    /**
+     * Creates a new {@link AgentManager}.
+     *
+     * This constructor is **exposed for testing only** so unit tests can inject a stubbed
+     * {@link AgentHarness} and deterministic ID generator.
+     *
+     * Production callers should use {@link createAgentManager} instead.
+     *
+     * @example
+     * ```ts
+     * // Recommended for production usage (constructs the default connectivity resolver):
+     * const manager = await createAgentManager(storageRootFolder, harnessFactory);
+     * ```
+     */
+    constructor(harness, agentConnectivityResolver, agentIdGenerator = new UUIDGenerator(), clock = new RealClock(), logBus = new LogBus()) {
+        this.harness = harness;
+        this.agentConnectivityResolver = agentConnectivityResolver;
+        this.agentIdGenerator = agentIdGenerator;
+        this.clock = clock;
+        this.logBus = logBus;
+        this.router = new TelemetryRouter(harness);
+        this.unroutedUnsubs = [
+            this.router.unrouted.telemetry.forwardTo(this.telemetryBus),
+            this.router.unrouted.log.forwardTo(this.logBus),
+        ];
+    }
+    // Note: harness construction is async (see createAgentManager), so AgentManager itself no longer has initialize().
+    /**
+     * Shuts down the harness and destroys all managed agents.
+     *
+     * @requirements
+     * - MUST iterate through all agents in the internal `agents` map and call `agent.destroy()` on each.
+     * - MUST clear the internal `agents` map.
+     * - MUST delegate to `this.harness.shutdown()` to release harness-level resources.
+     */
+    async shutdown() {
+        if (this.disposed) {
+            return;
+        }
+        for (const [agentId, agent] of this.agents) {
+            await agent.destroy();
+            this.router.unregisterAgent(agentId);
+        }
+        this.agents.clear();
+        await this.harness.shutdown();
+        for (const unsub of this.unroutedUnsubs)
+            unsub();
+        this.router.dispose();
+        this.telemetryBus.dispose();
+        this.logBus.dispose();
+        this.disposed = true;
+    }
+    /**
+     * Creates a new `Agent` with the given configuration.
+     *
+     * @param projectRoot - Absolute path to the project folder the agent can manipulate files from.
+     *   Relative paths are resolved against `process.cwd()`. The path must exist and be a directory.
+     * @param config - Agent configuration (instructions, tools, model, etc.).
+     * @param options - Optional execution options, including abort signals.
+     * @returns A new `Agent` ready for chat sessions.
+     *
+     * @throws If `projectRoot` does not exist or is not a directory.
+     *
+     * @requirements
+     * - MUST resolve `projectRoot` to an absolute, normalized path before use.
+     * - MUST throw an Error if the resolved `projectRoot` does not exist or is not a directory.
+     * - MUST throw an Error if `config.agentId` is provided and an agent with that ID already exists in the internal `agents` map.
+     * - MUST generate a unique ID via `this.agentIdGenerator` if `config.agentId` is omitted.
+     * - MUST delegate to `this.harness.createAgent(agentId, projectRoot, llmGatewayClient, config, options)` to register the agent in the harness and allow for cancellation.
+     * - MUST instantiate a `DefaultAgent` with the harness and the complete configuration.
+     * - MUST store the newly created agent in the internal `agents` map, keyed by its `agentId`.
+     * - MUST return the newly created agent.
+     */
+    async createAgent(projectRoot, config = {}, options) {
+        this.assertNotDisposed();
+        const resolvedProjectRoot = resolve(projectRoot);
+        let dirStat;
+        try {
+            dirStat = await stat(resolvedProjectRoot);
+        }
+        catch {
+            throw new Error(`projectRoot does not exist: "${resolvedProjectRoot}"`);
+        }
+        if (!dirStat.isDirectory()) {
+            throw new Error(`projectRoot is not a directory: "${resolvedProjectRoot}"`);
+        }
+        const { agentId: providedAgentId, ...agentConfig } = config;
+        const agentId = providedAgentId ?? this.agentIdGenerator.getUniqueId();
+        if (providedAgentId && this.agents.has(providedAgentId)) {
+            throw new Error(`Agent with id "${providedAgentId}" already exists`);
+        }
+        const runtime = await this.agentConnectivityResolver.resolve(resolvedProjectRoot, agentConfig);
+        await this.harness.createAgent(agentId, resolvedProjectRoot, runtime.llmGatewayClient, toHarnessConfig(agentConfig, runtime.orgJwt), options);
+        const agentSlice = this.router.registerAgent(agentId);
+        const agent = new DefaultAgent(this.harness, agentId, resolvedProjectRoot, agentConfig, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        this.agents.set(agentId, agent);
+        this.telemetryBus.emit({
+            type: 'agent-created',
+            timestamp: this.clock.now(),
+            agentId,
+            projectRoot: resolvedProjectRoot,
+            modelName: runtime.llmGatewayClient.getModel().name,
+        });
+        return agent;
+    }
+    /**
+     * Returns the IDs of all currently managed agents.
+     *
+     * @requirements
+     * - MUST return an array of all string keys (agent IDs) currently tracked in the internal `agents` map.
+     */
+    getAgentIds() {
+        this.assertNotDisposed();
+        return Array.from(this.agents.keys());
+    }
+    /**
+     * Retrieves a managed agent by its ID.
+     *
+     * @param agentId - ID of the agent to retrieve.
+     *
+     * @requirements
+     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
+     * - MUST return the `Agent` instance associated with the given `agentId`.
+     */
+    getAgent(agentId) {
+        this.assertNotDisposed();
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        return agent;
+    }
+    /**
+     * Destroys a managed agent by its ID, releasing all its resources.
+     *
+     * @param agentId - ID of the agent to destroy.
+     *
+     * @requirements
+     * - MUST throw an Error if the provided `agentId` is not found in the internal `agents` map.
+     * - MUST call `destroy()` on the target agent instance.
+     * - MUST remove the agent from the internal `agents` map.
+     */
+    async destroyAgent(agentId) {
+        this.assertNotDisposed();
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
+        }
+        await agent.destroy();
+        this.router.unregisterAgent(agentId);
+        this.agents.delete(agentId);
+    }
+    /** Subscribe to telemetry events across every managed agent. Returns an unsubscribe function. */
+    onTelemetry(callback) {
+        this.assertNotDisposed();
+        return this.telemetryBus.on(callback);
+    }
+    /** Subscribe to structured log records across every managed agent. Returns an unsubscribe function. */
+    onLog(callback) {
+        this.assertNotDisposed();
+        return this.logBus.on(callback);
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw new AgentSDKError('AgentManager has been shut down.', AgentSDKErrorType.DISPOSED);
+        }
+    }
+}
+/**
+ * Creates an {@link AgentManager} using the provided harness factory.
+ *
+ * Use this function in production code. It validates the `storageRootFolder`,
+ * verifies the factory advertises a supported protocol version (failing fast
+ * before any expensive harness construction), constructs the harness
+ * asynchronously, sanity-checks that the constructed harness honors the
+ * factory's advertised version, and returns a ready-to-use manager.
+ *
+ * @param storageRootFolder - Existing directory used for agent persistence.
+ * @param harnessFactory - Factory that constructs the harness implementation.
+ *
+ * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
+ *   the constructed harness reports a `protocolVersion` outside
+ *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
+ *   version disagrees with the factory's.
+ */
+export async function createAgentManager(storageRootFolder, harnessFactory) {
+    let stats;
+    try {
+        stats = await stat(storageRootFolder);
+    }
+    catch {
+        throw new Error(`storageRootFolder does not exist: "${storageRootFolder}"`);
+    }
+    if (!stats.isDirectory()) {
+        throw new Error(`storageRootFolder is not a directory: "${storageRootFolder}"`);
+    }
+    const factoryVersion = harnessFactory.protocolVersion;
+    if (!isSupportedProtocolVersion(factoryVersion)) {
+        throw new AgentSDKError(`Harness "${harnessFactory.harnessId}" advertises protocolVersion ${String(factoryVersion)} ` +
+            `which is not supported by this SDK (supported: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}). ` +
+            `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
+    }
+    const harness = await harnessFactory.create(storageRootFolder);
+    const harnessVersion = harness.protocolVersion;
+    const harnessVersionMismatch = !isSupportedProtocolVersion(harnessVersion) || harnessVersion !== factoryVersion;
+    if (harnessVersionMismatch) {
+        try {
+            await harness.shutdown();
+        }
+        catch (shutdownError) {
+            // We have no LogBus at this stage (AgentManager not constructed yet),
+            // so surface the swallowed error instead of silently dropping it.
+            console.warn('[sfdx-agent-sdk] harness.shutdown() failed during INCOMPATIBLE_HARNESS rejection:', shutdownError);
+        }
+        throw new AgentSDKError(`Harness "${harness.harnessId}" returned by factory "${harnessFactory.harnessId}" ` +
+            `reports protocolVersion ${String(harnessVersion)} which does not match the factory's ` +
+            `advertised version ${factoryVersion} (SDK supports: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}). ` +
+            `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
+    }
+    const agentConnectivityResolver = new DefaultAgentConnectivityResolver();
+    return new AgentManager(harness, agentConnectivityResolver, new UUIDGenerator());
+}
+function isSupportedProtocolVersion(version) {
+    return (typeof version === 'number' &&
+        Number.isFinite(version) &&
+        SUPPORTED_PROTOCOL_VERSIONS.includes(version));
+}
+//# sourceMappingURL=agent-manager.js.map

package/dist/agent-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manager.js","sourceRoot":"","sources":["../src/agent-manager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEH,QAAQ,EACR,MAAM,EAEN,SAAS,EAET,aAAa,GAEhB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,2BAA2B,EAAqB,MAAM,4BAA4B,CAAC;AAE5F,OAAO,EAAoB,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAGjE,OAAO,EAAE,gCAAgC,EAAkC,MAAM,kCAAkC,CAAC;AAEpH;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,YAAY;IACJ,OAAO,CAAe;IACtB,gBAAgB,CAAoB;IACpC,yBAAyB,CAA4B;IACrD,KAAK,CAAQ;IACb,MAAM,GAA8B,IAAI,GAAG,EAAE,CAAC;IAC9C,YAAY,GAAiB,IAAI,QAAQ,EAAkB,CAAC;IAC5D,MAAM,CAAS;IACf,MAAM,CAAkB;IACxB,cAAc,CAAgB;IACvC,QAAQ,GAAY,KAAK,CAAC;IAElC;;;;;;;;;;;;;OAaG;IACH,YACI,OAAqB,EACrB,yBAAoD,EACpD,mBAAsC,IAAI,aAAa,EAAE,EACzD,QAAe,IAAI,SAAS,EAAE,EAC9B,SAAiB,IAAI,MAAM,EAAE;QAE7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,yBAAyB,GAAG,yBAAyB,CAAC;QAC3D,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,CAAC,cAAc,GAAG;YAClB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC;YAC3D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;SAClD,CAAC;IACN,CAAC;IAED,mHAAmH;IAEnH;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ;QACV,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,OAAO;QACX,CAAC;QACD,KAAK,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACzC,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;YACtB,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAEpB,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QAE9B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc;YAAE,KAAK,EAAE,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACtB,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;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,WAAW,CACb,WAAmB,EACnB,SAA6C,EAAE,EAC/C,OAAuC;QAEvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,OAAO,CAAC;QACZ,IAAI,CAAC;YACD,OAAO,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACL,MAAM,IAAI,KAAK,CAAC,gCAAgC,mBAAmB,GAAG,CAAC,CAAC;QAC5E,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,oCAAoC,mBAAmB,GAAG,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,WAAW,EAAE,GAAG,MAAM,CAAC;QAC5D,MAAM,OAAO,GAAG,eAAe,IAAI,IAAI,CAAC,gBAAgB,CAAC,WAAW,EAAE,CAAC;QAEvE,IAAI,eAAe,IAAI,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,kBAAkB,eAAe,kBAAkB,CAAC,CAAC;QACzE,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAC;QAE/F,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAC1B,OAAO,EACP,mBAAmB,EACnB,OAAO,CAAC,gBAAgB,EACxB,eAAe,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,EAC5C,OAAO,CACV,CAAC;QAEF,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACtD,MAAM,KAAK,GAAG,IAAI,YAAY,CAC1B,IAAI,CAAC,OAAO,EACZ,OAAO,EACP,mBAAmB,EACnB,WAAW,EACX,OAAO,CAAC,gBAAgB,EACxB,OAAO,CAAC,aAAa,EACrB,OAAO,CAAC,MAAM,EACd,IAAI,CAAC,yBAAyB,EAC9B,IAAI,CAAC,MAAM,EACX,UAAU,EACV,EAAE,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,EAAE,EAClD,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,gBAAgB,CACxB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;YACnB,IAAI,EAAE,eAAe;YACrB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YAC3B,OAAO;YACP,WAAW,EAAE,mBAAmB;YAChC,SAAS,EAAE,OAAO,CAAC,gBAAgB,CAAC,QAAQ,EAAE,CAAC,IAAI;SACtD,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,WAAW;QACP,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAe;QACpB,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,aAAa,CAAC,4BAA4B,OAAO,GAAG,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;QACvG,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,YAAY,CAAC,OAAe;QAC9B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,MAAM,IAAI,aAAa,CAAC,4BAA4B,OAAO,GAAG,EAAE,iBAAiB,CAAC,eAAe,CAAC,CAAC;QACvG,CAAC;QACD,MAAM,KAAK,CAAC,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAED,iGAAiG;IACjG,WAAW,CAAC,QAAgC;QACxC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,uGAAuG;IACvG,KAAK,CAAC,QAAqC;QACvC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAEO,iBAAiB;QACrB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,MAAM,IAAI,aAAa,CAAC,kCAAkC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;QAC5F,CAAC;IACL,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACpC,iBAAyB,EACzB,cAA8B;IAE9B,IAAI,KAAK,CAAC;IACV,IAAI,CAAC;QACD,KAAK,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACL,MAAM,IAAI,KAAK,CAAC,sCAAsC,iBAAiB,GAAG,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,0CAA0C,iBAAiB,GAAG,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,cAAc,GAAG,cAAc,CAAC,eAAe,CAAC;IACtD,IAAI,CAAC,0BAA0B,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,aAAa,CACnB,YAAY,cAAc,CAAC,SAAS,gCAAgC,MAAM,CAAC,cAAc,CAAC,GAAG;YACzF,kDAAkD,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAC7F,oCAAoC,EACxC,iBAAiB,CAAC,oBAAoB,CACzC,CAAC;IACN,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC/D,MAAM,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAC/C,MAAM,sBAAsB,GAAG,CAAC,0BAA0B,CAAC,cAAc,CAAC,IAAI,cAAc,KAAK,cAAc,CAAC;IAEhH,IAAI,sBAAsB,EAAE,CAAC;QACzB,IAAI,CAAC;YACD,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC7B,CAAC;QAAC,OAAO,aAAa,EAAE,CAAC;YACrB,sEAAsE;YACtE,kEAAkE;YAClE,OAAO,CAAC,IAAI,CACR,mFAAmF,EACnF,aAAa,CAChB,CAAC;QACN,CAAC;QACD,MAAM,IAAI,aAAa,CACnB,YAAY,OAAO,CAAC,SAAS,0BAA0B,cAAc,CAAC,SAAS,IAAI;YAC/E,2BAA2B,MAAM,CAAC,cAAc,CAAC,sCAAsC;YACvF,sBAAsB,cAAc,mBAAmB,2BAA2B,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAClG,oCAAoC,EACxC,iBAAiB,CAAC,oBAAoB,CACzC,CAAC;IACN,CAAC;IAED,MAAM,yBAAyB,GAAG,IAAI,gCAAgC,EAAE,CAAC;IACzE,OAAO,IAAI,YAAY,CAAC,OAAO,EAAE,yBAAyB,EAAE,IAAI,aAAa,EAAE,CAAC,CAAC;AACrF,CAAC;AAED,SAAS,0BAA0B,CAAC,OAAgB;IAChD,OAAO,CACH,OAAO,OAAO,KAAK,QAAQ;QAC3B,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QACvB,2BAAiD,CAAC,QAAQ,CAAC,OAAO,CAAC,CACvE,CAAC;AACN,CAAC"}

package/dist/agent.d.ts

@@ -0,0 +1,218 @@
+import { type Clock, LogBus, type LogRecord, type OrgConnection, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
+import type { AgentHarness } from './harness/agent-harness.js';
+import { type AgentConfig } from './harness/harness-config.js';
+import { type ChatSession } from './chat-session.js';
+import type { McpServerInfo } from './mcp-config.js';
+import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import type { AgentConnectivityResolver } from './agent-connectivity-resolver.js';
+import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
+import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
+/**
+ * Parent bus pair wired at construction time so an agent's events bubble upward into the manager's buses.
+ */
+export type AgentParentBuses = {
+    telemetry: TelemetryBus;
+    log: LogBus;
+};
+/**
+ * Represents a configured agent managed by the {@link AgentManager}.
+ *
+ * Each `Agent` wraps a single agent in the underlying harness. It
+ * provides agent-level operations (configuration, MCP, lifecycle) and serves
+ * as the factory for {@link ChatSession} instances.
+ */
+export interface Agent {
+    /** Returns the unique agent identifier. */
+    getId(): string;
+    /** Returns the project root folder this agent operates within. */
+    getProjectRoot(): string;
+    /** Returns the authenticated org connection for the org this agent runs under. */
+    getOrgConnection(): OrgConnection;
+    /** Returns the current agent configuration. */
+    getAgentConfig(): AgentConfig;
+    /**
+     * Returns runtime information about MCP servers attached to this agent,
+     * including connection status and discovered tool names. This is a synchronous
+     * snapshot — status is updated asynchronously by background discovery promises.
+     */
+    getMcpServerInfo(): McpServerInfo[];
+    /**
+     * Update the agent's configuration. The harness applies the changes
+     * to the live agent (e.g., new instructions, tools, model).
+     *
+     * @param config - Partial configuration to merge with the current config.
+     * @param options - Optional execution options, including abort signals.
+     */
+    updateAgentConfig(config?: AgentConfig, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Create a new chat session (conversation thread) for this agent.
+     * @returns A new {@link ChatSession} with a unique thread ID.
+     */
+    createChatSession(): Promise<ChatSession>;
+    /**
+     * Destroy a chat session and its message history.
+     * @param sessionId - ID of the session to destroy.
+     */
+    destroyChatSession(sessionId: string): Promise<void>;
+    /**
+     * Retrieve an existing chat session by its ID.
+     * @param sessionId - ID of the session to retrieve.
+     * @throws Error if no session with the given ID exists.
+     */
+    getChatSession(sessionId: string): ChatSession;
+    /**
+     * List all active session IDs for this agent.
+     */
+    getChatSessionIds(): string[];
+    /**
+     * Clone an existing chat session, creating a new session with copied
+     * message history.
+     *
+     * @param sourceSessionId - ID of the session to clone.
+     * @returns A new {@link ChatSession} with cloned history.
+     */
+    cloneChatSession(sourceSessionId: string): Promise<ChatSession>;
+    /**
+     * Compact a chat session's message history to reduce context window usage.
+     * Creates a new session seeded with an LLM-generated summary of the
+     * source session's conversation.
+     *
+     * @param sessionId - ID of the session to compact.
+     * @returns A new {@link ChatSession} with the compacted summary.
+     */
+    compactChatSession(sessionId: string): Promise<ChatSession>;
+    /**
+     * Destroy this agent and release all resources (MCP connections,
+     * workspace, memory, and all sessions).
+     */
+    destroy(): Promise<void>;
+    /** Subscribe to telemetry events scoped to this agent (and its sessions). Returns an unsubscribe function. */
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    /** Subscribe to structured log records scoped to this agent (and its sessions). Returns an unsubscribe function. */
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+}
+/**
+ * Default implementation of {@link Agent} that delegates
+ * agent and thread operations to an {@link AgentHarness}.
+ */
+export declare class DefaultAgent implements Agent {
+    private readonly harness;
+    private readonly agentId;
+    private readonly projectRoot;
+    private config;
+    private llmGatewayClient;
+    private orgConnection;
+    private orgJwt;
+    private readonly agentConnectivityResolver;
+    private readonly sessions;
+    private readonly sessionSliceUnregisters;
+    private readonly router;
+    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 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: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    /**
+     * @requirements
+     * - MUST return the agent's ID.
+     */
+    getId(): string;
+    /** Returns the project root folder this agent operates within. */
+    getProjectRoot(): string;
+    getOrgConnection(): OrgConnection;
+    /**
+     * @requirements
+     * - MUST return a shallow copy of the internal `config` object to prevent external mutation of the agent's state.
+     */
+    getAgentConfig(): AgentConfig;
+    getMcpServerInfo(): McpServerInfo[];
+    /**
+     * @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.
+     */
+    updateAgentConfig(config?: AgentConfig, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * @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.
+     */
+    createChatSession(): Promise<ChatSession>;
+    /**
+     * @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.
+     */
+    destroyChatSession(sessionId: string): Promise<void>;
+    /**
+     * @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: string): ChatSession;
+    /**
+     * @requirements
+     * - MUST return an array of all string keys (session IDs) currently tracked in the internal `sessions` map.
+     */
+    getChatSessionIds(): string[];
+    /**
+     * @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.
+     */
+    cloneChatSession(sourceSessionId: string): Promise<ChatSession>;
+    /**
+     * @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.
+     */
+    compactChatSession(sessionId: string): Promise<ChatSession>;
+    /**
+     * @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.
+     */
+    destroy(): Promise<void>;
+    onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
+    onLog(callback: (record: LogRecord) => void): Unsubscribe;
+    private attachSession;
+    private detachSession;
+    private assertNotDisposed;
+}