@inkeep/agents-core 0.41.2 → 0.43.0

package/dist/api-client/base-client.d.ts

@@ -1,11 +1,7 @@
+import { InternalServiceId } from "../utils/internal-service-auth.js";
+
 //#region src/api-client/base-client.d.ts
-/**
- * Shared base API client for making HTTP requests
- * Used by both CLI and SDK to ensure consistent API communication
- *
- * This is a thin wrapper around fetch that provides consistent header handling.
- * Implementations should construct Authorization headers and pass them via options.
- */
+
 /**
  * Makes an HTTP request with consistent header defaults
  *
@@ -31,5 +27,88 @@
  * ```
  */
 declare function apiFetch(url: string, options?: RequestInit): Promise<Response>;
+declare class BaseApiError extends Error {
+  readonly statusCode: number;
+  readonly responseBody: string;
+  constructor(message: string, statusCode: number, responseBody: string);
+  get isNotFound(): boolean;
+  get isUnauthorized(): boolean;
+  get isForbidden(): boolean;
+}
+type BaseApiClientAuth = {
+  mode: 'internalService';
+  internalServiceName: InternalServiceId;
+} | {
+  mode: 'apiKey';
+  apiKey: string;
+  isCI?: boolean;
+};
+interface BaseApiClientConfig {
+  apiUrl: string;
+  tenantId: string;
+  projectId: string;
+  auth: BaseApiClientAuth;
+  ref?: string;
+  userId?: string;
+  userEmail?: string;
+}
+declare abstract class BaseApiClient {
+  protected apiUrl: string;
+  protected tenantId: string | undefined;
+  protected projectId: string;
+  protected apiKey: string | undefined;
+  protected isCI: boolean;
+  protected internalServiceName?: InternalServiceId;
+  protected ref?: string;
+  protected userId?: string;
+  protected userEmail?: string;
+  protected constructor(config: BaseApiClientConfig);
+  protected checkTenantId(): string;
+  /**
+   * Builds a URL from the base API URL and a path
+   * Supports optional ref and pagination query parameters
+   */
+  protected buildUrl(path: string, params?: {
+    page?: number;
+    limit?: number;
+  }): string;
+  /**
+   * Gets auth headers for requests
+   * Handles both internal service JWT tokens and API key authentication
+   */
+  protected getAuthHeaders(): Promise<Record<string, string>>;
+  /**
+   * Wrapper around fetch that automatically includes auth header
+   * Uses X-API-Key for CI mode, Authorization Bearer for interactive mode
+   * @deprecated Use getAuthHeaders() with apiFetch() instead for more flexibility
+   */
+  protected authenticatedFetch(url: string, options?: RequestInit): Promise<Response>;
+  /**
+   * Creates an error instance for failed requests
+   * Override in subclasses to return specific error types
+   */
+  protected createError(message: string, statusCode: number, responseBody: string): BaseApiError;
+  /**
+   * Extracts data from a successful response
+   * Override in subclasses if the API wraps responses (e.g., { data: ... })
+   */
+  protected extractResponseData<T>(response: Response): Promise<T>;
+  /**
+   * Makes a GET request with authentication
+   */
+  protected makeGetRequest<T>(path: string, errorContext: string): Promise<T>;
+  /**
+   * Makes a POST request with authentication
+   */
+  protected makePostRequest<T>(path: string, body: unknown, errorContext: string): Promise<T>;
+  /**
+   * Makes paginated GET requests and collects all results
+   */
+  protected makePaginatedGetRequest<T>(path: string, errorContext: string, pageSize?: number): Promise<T[]>;
+  getTenantId(): string | undefined;
+  getProjectId(): string;
+  getApiUrl(): string;
+  getIsCI(): boolean;
+}
 //#endregion
-export { apiFetch };
+export { BaseApiClient, BaseApiClientAuth, BaseApiClientConfig, BaseApiError, apiFetch };

package/dist/api-client/base-client.js

@@ -1,3 +1,5 @@
+import { generateInternalServiceToken } from "../utils/internal-service-auth.js";
+
 //#region src/api-client/base-client.ts
 /**
 * Shared base API client for making HTTP requests
@@ -41,6 +43,177 @@ async function apiFetch(url, options = {}) {
 		headers
 	});
 }
+var BaseApiError = class extends Error {
+	constructor(message, statusCode, responseBody) {
+		super(message);
+		this.statusCode = statusCode;
+		this.responseBody = responseBody;
+		this.name = "BaseApiError";
+	}
+	get isNotFound() {
+		return this.statusCode === 404;
+	}
+	get isUnauthorized() {
+		return this.statusCode === 401;
+	}
+	get isForbidden() {
+		return this.statusCode === 403;
+	}
+};
+var BaseApiClient = class {
+	apiUrl;
+	tenantId;
+	projectId;
+	apiKey;
+	isCI;
+	internalServiceName;
+	ref;
+	userId;
+	userEmail;
+	constructor(config) {
+		this.apiUrl = config.apiUrl;
+		this.tenantId = config.tenantId;
+		this.projectId = config.projectId;
+		this.apiKey = config.auth.mode === "apiKey" ? config.auth.apiKey : void 0;
+		this.isCI = config.auth.mode === "apiKey" ? config.auth.isCI ?? false : false;
+		this.internalServiceName = config.auth.mode === "internalService" ? config.auth.internalServiceName : void 0;
+		this.ref = config.ref;
+		this.userId = config.userId;
+		this.userEmail = config.userEmail;
+	}
+	checkTenantId() {
+		if (!this.tenantId) throw new Error("No tenant ID configured. Please run: inkeep init");
+		return this.tenantId;
+	}
+	/**
+	* Builds a URL from the base API URL and a path
+	* Supports optional ref and pagination query parameters
+	*/
+	buildUrl(path, params) {
+		const normalizedBase = this.apiUrl.replace(/\/$/, "");
+		const url = new URL(`${normalizedBase}${path}`);
+		if (this.ref !== void 0 && this.ref !== "main") url.searchParams.set("ref", this.ref);
+		if (params?.page !== void 0) url.searchParams.set("page", String(params.page));
+		if (params?.limit !== void 0) url.searchParams.set("limit", String(params.limit));
+		return url.toString();
+	}
+	/**
+	* Gets auth headers for requests
+	* Handles both internal service JWT tokens and API key authentication
+	*/
+	async getAuthHeaders() {
+		const tenantId = this.checkTenantId();
+		if (this.internalServiceName) return { Authorization: `Bearer ${await generateInternalServiceToken({
+			serviceId: this.internalServiceName,
+			tenantId,
+			projectId: this.projectId,
+			userId: this.userId
+		})}` };
+		if (this.apiKey) {
+			if (this.isCI) return { "X-API-Key": this.apiKey };
+			return { Authorization: `Bearer ${this.apiKey}` };
+		}
+		return {};
+	}
+	/**
+	* Wrapper around fetch that automatically includes auth header
+	* Uses X-API-Key for CI mode, Authorization Bearer for interactive mode
+	* @deprecated Use getAuthHeaders() with apiFetch() instead for more flexibility
+	*/
+	async authenticatedFetch(url, options = {}) {
+		const headers = { ...options.headers || {} };
+		if (this.apiKey) if (this.isCI) headers["X-API-Key"] = this.apiKey;
+		else headers.Authorization = `Bearer ${this.apiKey}`;
+		return apiFetch(url, {
+			...options,
+			headers
+		});
+	}
+	/**
+	* Creates an error instance for failed requests
+	* Override in subclasses to return specific error types
+	*/
+	createError(message, statusCode, responseBody) {
+		return new BaseApiError(message, statusCode, responseBody);
+	}
+	/**
+	* Extracts data from a successful response
+	* Override in subclasses if the API wraps responses (e.g., { data: ... })
+	*/
+	async extractResponseData(response) {
+		return response.json();
+	}
+	/**
+	* Makes a GET request with authentication
+	*/
+	async makeGetRequest(path, errorContext) {
+		const response = await apiFetch(this.buildUrl(path), {
+			method: "GET",
+			headers: await this.getAuthHeaders()
+		});
+		if (!response.ok) {
+			const errorBody = await response.text().catch(() => "Unknown error");
+			throw this.createError(`${errorContext}: ${response.status} ${response.statusText}`, response.status, errorBody);
+		}
+		return this.extractResponseData(response);
+	}
+	/**
+	* Makes a POST request with authentication
+	*/
+	async makePostRequest(path, body, errorContext) {
+		const response = await apiFetch(this.buildUrl(path), {
+			method: "POST",
+			headers: {
+				...await this.getAuthHeaders(),
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body)
+		});
+		if (!response.ok) {
+			const errorBody = await response.text().catch(() => "Unknown error");
+			throw this.createError(`${errorContext}: ${response.status} ${response.statusText}`, response.status, errorBody);
+		}
+		return this.extractResponseData(response);
+	}
+	/**
+	* Makes paginated GET requests and collects all results
+	*/
+	async makePaginatedGetRequest(path, errorContext, pageSize = 100) {
+		const allItems = [];
+		let currentPage = 1;
+		const headers = await this.getAuthHeaders();
+		while (true) {
+			const response = await apiFetch(this.buildUrl(path, {
+				page: currentPage,
+				limit: pageSize
+			}), {
+				method: "GET",
+				headers
+			});
+			if (!response.ok) {
+				const errorBody = await response.text().catch(() => "Unknown error");
+				throw this.createError(`${errorContext}: ${response.status} ${response.statusText}`, response.status, errorBody);
+			}
+			const json = await response.json();
+			allItems.push(...json.data);
+			if (currentPage >= json.pagination.pages) break;
+			currentPage++;
+		}
+		return allItems;
+	}
+	getTenantId() {
+		return this.tenantId;
+	}
+	getProjectId() {
+		return this.projectId;
+	}
+	getApiUrl() {
+		return this.apiUrl;
+	}
+	getIsCI() {
+		return this.isCI;
+	}
+};
 
 //#endregion
-export { apiFetch };
+export { BaseApiClient, BaseApiError, apiFetch };

package/dist/api-client/eval-api-client.d.ts

@@ -0,0 +1,47 @@
+import { BaseApiClient, BaseApiClientConfig, BaseApiError } from "./base-client.js";
+import { TriggerConversationEvaluationRequest, TriggerDatasetRunRequest, TriggerEvaluationJobRequest } from "../types/entities.js";
+
+//#region src/api-client/eval-api-client.d.ts
+declare class EvalApiError extends BaseApiError {
+  constructor(message: string, statusCode: number, responseBody: string);
+}
+interface TriggerDatasetRunResponse {
+  queued: number;
+  failed: number;
+  datasetRunId: string;
+}
+interface TriggerConversationEvaluationResponse {
+  success: boolean;
+  message: string;
+  evaluationsTriggered: number;
+}
+interface TriggerBatchConversationEvaluationResponse {
+  queued: number;
+  failed: number;
+}
+interface TriggerEvaluationJobResponse {
+  queued: number;
+  failed: number;
+  evaluationRunId: string;
+  conversationCount: number;
+}
+declare class EvalApiClient extends BaseApiClient {
+  constructor(config: BaseApiClientConfig);
+  /**
+   * Override to return EvalApiError
+   */
+  protected createError(message: string, statusCode: number, responseBody: string): EvalApiError;
+  /**
+   * Trigger a dataset run workflow
+   * Enqueues dataset items for processing through the chat API
+   */
+  triggerDatasetRun(request: TriggerDatasetRunRequest): Promise<TriggerDatasetRunResponse>;
+  /**
+   * Trigger an evaluation job
+   * Filters conversations based on job filters, creates an evaluation run, and enqueues workflows
+   */
+  triggerEvaluationJob(request: TriggerEvaluationJobRequest): Promise<TriggerEvaluationJobResponse>;
+  triggerConversationEvaluation(request: TriggerConversationEvaluationRequest): Promise<TriggerConversationEvaluationResponse>;
+}
+//#endregion
+export { EvalApiClient, EvalApiError, TriggerBatchConversationEvaluationResponse, TriggerConversationEvaluationResponse, TriggerDatasetRunResponse, TriggerEvaluationJobResponse };

package/dist/api-client/eval-api-client.js

@@ -0,0 +1,65 @@
+import { getLogger } from "../utils/logger.js";
+import { BaseApiClient, BaseApiError } from "./base-client.js";
+
+//#region src/api-client/eval-api-client.ts
+const logger = getLogger("eval-api-client");
+var EvalApiError = class extends BaseApiError {
+	constructor(message, statusCode, responseBody) {
+		super(message, statusCode, responseBody);
+		this.name = "EvalApiError";
+	}
+};
+var EvalApiClient = class extends BaseApiClient {
+	constructor(config) {
+		super(config);
+	}
+	/**
+	* Override to return EvalApiError
+	*/
+	createError(message, statusCode, responseBody) {
+		return new EvalApiError(message, statusCode, responseBody);
+	}
+	/**
+	* Trigger a dataset run workflow
+	* Enqueues dataset items for processing through the chat API
+	*/
+	async triggerDatasetRun(request) {
+		const tenantId = this.checkTenantId();
+		const path = `/tenants/${tenantId}/projects/${this.projectId}/run-dataset-items`;
+		logger.info({
+			tenantId,
+			projectId: this.projectId,
+			datasetRunId: request.datasetRunId,
+			itemCount: request.items.length
+		}, "Triggering dataset run workflow");
+		return this.makePostRequest(path, request, "Failed to trigger dataset run workflow");
+	}
+	/**
+	* Trigger an evaluation job
+	* Filters conversations based on job filters, creates an evaluation run, and enqueues workflows
+	*/
+	async triggerEvaluationJob(request) {
+		const tenantId = this.checkTenantId();
+		const path = `/tenants/${tenantId}/projects/${this.projectId}/evaluate-conversations-by-job`;
+		logger.info({
+			tenantId,
+			projectId: this.projectId,
+			evaluationJobConfigId: request.evaluationJobConfigId,
+			evaluatorCount: request.evaluatorIds.length
+		}, "Triggering evaluation job workflow");
+		return this.makePostRequest(path, request, "Failed to trigger evaluation job workflow");
+	}
+	async triggerConversationEvaluation(request) {
+		const tenantId = this.checkTenantId();
+		const path = `/tenants/${tenantId}/projects/${this.projectId}/evaluate-conversation`;
+		logger.info({
+			tenantId,
+			projectId: this.projectId,
+			conversationId: request.conversationId
+		}, "Triggering conversation evaluation workflow");
+		return this.makePostRequest(path, request, "Failed to trigger conversation evaluation workflow");
+	}
+};
+
+//#endregion
+export { EvalApiClient, EvalApiError };

package/dist/api-client/index.d.ts

@@ -0,0 +1,4 @@
+import { BaseApiClient, BaseApiClientAuth, BaseApiClientConfig, BaseApiError, apiFetch } from "./base-client.js";
+import { ManageApiError, ManagementApiClient } from "./manage-api-client.js";
+import { EvalApiClient, EvalApiError, TriggerBatchConversationEvaluationResponse, TriggerConversationEvaluationResponse, TriggerDatasetRunResponse, TriggerEvaluationJobResponse } from "./eval-api-client.js";
+export { BaseApiClient, BaseApiClientAuth, BaseApiClientConfig, BaseApiError, EvalApiClient, EvalApiError, ManageApiError, ManagementApiClient, TriggerBatchConversationEvaluationResponse, TriggerConversationEvaluationResponse, TriggerDatasetRunResponse, TriggerEvaluationJobResponse, apiFetch };

package/dist/api-client/index.js

@@ -0,0 +1,5 @@
+import { BaseApiClient, BaseApiError, apiFetch } from "./base-client.js";
+import { EvalApiClient, EvalApiError } from "./eval-api-client.js";
+import { ManageApiError, ManagementApiClient } from "./manage-api-client.js";
+
+export { BaseApiClient, BaseApiError, EvalApiClient, EvalApiError, ManageApiError, ManagementApiClient, apiFetch };

package/dist/api-client/manage-api-client.d.ts

@@ -0,0 +1,34 @@
+import { BaseApiClient, BaseApiClientConfig, BaseApiError } from "./base-client.js";
+import { ResolvedRef } from "../validation/dolt-schemas.js";
+import { EvaluationJobConfigEvaluatorRelationSelect, EvaluationJobConfigSelect, EvaluationRunConfigWithSuiteConfigs, EvaluationSuiteConfigEvaluatorRelationSelect, EvaluationSuiteConfigSelect, EvaluatorSelect, FullAgentDefinition, FullProjectSelectWithRelationIds, FunctionToolApiSelect, McpTool } from "../types/entities.js";
+
+//#region src/api-client/manage-api-client.d.ts
+declare class ManageApiError extends BaseApiError {
+  constructor(message: string, statusCode: number, responseBody: string);
+}
+declare class ManagementApiClient extends BaseApiClient {
+  constructor(config: BaseApiClientConfig);
+  /**
+   * Override to return ManageApiError
+   */
+  protected createError(message: string, statusCode: number, responseBody: string): ManageApiError;
+  /**
+   * Override to extract data from { data: ... } wrapper
+   */
+  protected extractResponseData<T>(response: Response): Promise<T>;
+  getFullProject(): Promise<FullProjectSelectWithRelationIds>;
+  getResolvedRef(): Promise<ResolvedRef>;
+  getFullAgent(agentId: string): Promise<FullAgentDefinition | null>;
+  getMcpTool(toolId: string): Promise<McpTool>;
+  getFunctionToolsForSubAgent(agentId: string, subAgentId: string): Promise<FunctionToolApiSelect[]>;
+  getEvaluationJobConfigById(evaluationJobConfigId: string): Promise<EvaluationJobConfigSelect | null>;
+  getEvaluationJobConfigEvaluatorRelations(evaluationJobConfigId: string): Promise<EvaluationJobConfigEvaluatorRelationSelect[]>;
+  getEvaluatorById(evaluatorId: string): Promise<EvaluatorSelect | null>;
+  getEvaluatorsByIds(evaluatorIds: string[]): Promise<EvaluatorSelect[]>;
+  listEvaluationRunConfigs(): Promise<EvaluationRunConfigWithSuiteConfigs[]>;
+  getEvaluationRunConfigById(evaluationRunConfigId: string): Promise<EvaluationRunConfigWithSuiteConfigs | null>;
+  getEvaluationSuiteConfigById(evaluationSuiteConfigId: string): Promise<EvaluationSuiteConfigSelect | null>;
+  getEvaluationSuiteConfigEvaluatorRelations(evaluationSuiteConfigId: string): Promise<EvaluationSuiteConfigEvaluatorRelationSelect[]>;
+}
+//#endregion
+export { ManageApiError, ManagementApiClient };

package/dist/api-client/manage-api-client.js

@@ -0,0 +1,104 @@
+import { getLogger } from "../utils/logger.js";
+import { BaseApiClient, BaseApiError } from "./base-client.js";
+
+//#region src/api-client/manage-api-client.ts
+const logger = getLogger("manage-api-client");
+var ManageApiError = class extends BaseApiError {
+	constructor(message, statusCode, responseBody) {
+		super(message, statusCode, responseBody);
+		this.name = "ManageApiError";
+	}
+};
+var ManagementApiClient = class extends BaseApiClient {
+	constructor(config) {
+		super(config);
+	}
+	/**
+	* Override to return ManageApiError
+	*/
+	createError(message, statusCode, responseBody) {
+		return new ManageApiError(message, statusCode, responseBody);
+	}
+	/**
+	* Override to extract data from { data: ... } wrapper
+	*/
+	async extractResponseData(response) {
+		return (await response.json()).data;
+	}
+	async getFullProject() {
+		const path = `/tenants/${this.checkTenantId()}/project-full/${this.projectId}/with-relation-ids`;
+		return this.makeGetRequest(path, "Failed to fetch project config");
+	}
+	async getResolvedRef() {
+		const tenantId = this.checkTenantId();
+		logger.info({
+			tenantId,
+			projectId: this.projectId
+		}, "Resolving ref");
+		const path = `/tenants/${tenantId}/projects/${this.projectId}/refs/resolve`;
+		return this.makeGetRequest(path, "Failed to resolve ref");
+	}
+	async getFullAgent(agentId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/agent/${agentId}`;
+		try {
+			return await this.makeGetRequest(path, "Failed to fetch full agent");
+		} catch (error) {
+			if (error instanceof ManageApiError && error.isNotFound) return null;
+			throw error;
+		}
+	}
+	async getMcpTool(toolId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/tools/${toolId}`;
+		return this.makeGetRequest(path, "Failed to fetch MCP tool");
+	}
+	async getFunctionToolsForSubAgent(agentId, subAgentId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/agents/${agentId}/sub-agent-function-tools/sub-agent/${subAgentId}`;
+		return this.makePaginatedGetRequest(path, "Failed to fetch function tools for sub-agent");
+	}
+	async getEvaluationJobConfigById(evaluationJobConfigId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-job-configs/${evaluationJobConfigId}`;
+		try {
+			return await this.makeGetRequest(path, "Failed to fetch evaluation job config");
+		} catch (error) {
+			if (error instanceof ManageApiError && error.isNotFound) return null;
+			throw error;
+		}
+	}
+	async getEvaluationJobConfigEvaluatorRelations(evaluationJobConfigId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-job-configs/${evaluationJobConfigId}/evaluators`;
+		return this.makeGetRequest(path, "Failed to fetch evaluation job config evaluator relations");
+	}
+	async getEvaluatorById(evaluatorId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluators/${evaluatorId}`;
+		try {
+			return await this.makeGetRequest(path, "Failed to fetch evaluator");
+		} catch (error) {
+			if (error instanceof ManageApiError && error.isNotFound) return null;
+			throw error;
+		}
+	}
+	async getEvaluatorsByIds(evaluatorIds) {
+		if (evaluatorIds.length === 0) return [];
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluators/batch`;
+		return this.makePostRequest(path, { evaluatorIds }, "Failed to fetch evaluators batch");
+	}
+	async listEvaluationRunConfigs() {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-run-configs`;
+		return this.makePaginatedGetRequest(path, "Failed to list evaluation run configs");
+	}
+	async getEvaluationRunConfigById(evaluationRunConfigId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-run-configs/${evaluationRunConfigId}`;
+		return this.makeGetRequest(path, "Failed to fetch evaluation run config");
+	}
+	async getEvaluationSuiteConfigById(evaluationSuiteConfigId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-suite-configs/${evaluationSuiteConfigId}`;
+		return this.makeGetRequest(path, "Failed to fetch evaluation suite config");
+	}
+	async getEvaluationSuiteConfigEvaluatorRelations(evaluationSuiteConfigId) {
+		const path = `/tenants/${this.checkTenantId()}/projects/${this.projectId}/evals/evaluation-suite-configs/${evaluationSuiteConfigId}/evaluators`;
+		return this.makeGetRequest(path, "Failed to fetch evaluation suite config evaluator relations");
+	}
+};
+
+//#endregion
+export { ManageApiError, ManagementApiClient };