@inkeep/agents-run-api 0.39.4 → 0.40.0

package/dist/agents/ModelFactory.d.ts

@@ -0,0 +1,63 @@
+import { LanguageModel } from "ai";
+
+//#region src/agents/ModelFactory.d.ts
+interface ModelSettings {
+  model?: string;
+  providerOptions?: Record<string, unknown>;
+}
+/**
+ * Factory for creating AI SDK language models from configuration
+ * Supports multiple providers and AI Gateway integration
+ */
+declare class ModelFactory {
+  /**
+   * Create a provider instance with custom configuration
+   * Returns a provider with at least languageModel method
+   */
+  private static createProvider;
+  /**
+   * Extract provider configuration from providerOptions
+   * Only includes settings that go to the provider constructor (baseURL, apiKey, etc.)
+   */
+  private static extractProviderConfig;
+  /**
+   * Create a language model instance from configuration
+   * Throws error if no config provided - models must be configured at project level
+   */
+  static createModel(config: ModelSettings): LanguageModel;
+  /**
+   * Built-in providers that have special handling
+   */
+  private static readonly BUILT_IN_PROVIDERS;
+  /**
+   * Parse model string to extract provider and model name
+   * Examples: "anthropic/claude-sonnet-4" -> { provider: "anthropic", modelName: "claude-sonnet-4" }
+   *          "openrouter/anthropic/claude-sonnet-4" -> { provider: "openrouter", modelName: "anthropic/claude-sonnet-4" }
+   *          "claude-sonnet-4" -> { provider: "anthropic", modelName: "claude-sonnet-4" } (default to anthropic)
+   */
+  static parseModelString(modelString: string): {
+    provider: string;
+    modelName: string;
+  };
+  /**
+   * Get generation parameters from provider options
+   * These are parameters that get passed to generateText/streamText calls
+   */
+  static getGenerationParams(providerOptions?: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Prepare complete generation configuration from model settings
+   * Returns model instance and generation parameters ready to spread into generateText/streamText
+   * Includes maxDuration if specified in provider options (in seconds, following Vercel standard)
+   */
+  static prepareGenerationConfig(modelSettings?: ModelSettings): {
+    model: LanguageModel;
+    maxDuration?: number;
+  } & Record<string, unknown>;
+  /**
+   * Validate model settingsuration
+   * Basic validation only - let AI SDK handle parameter-specific validation
+   */
+  static validateConfig(config: ModelSettings): string[];
+}
+//#endregion
+export { ModelFactory, ModelSettings };

package/dist/agents/ModelFactory.js

@@ -0,0 +1,194 @@
+import { getLogger } from "../logger.js";
+import { anthropic, createAnthropic } from "@ai-sdk/anthropic";
+import { createGateway, gateway } from "@ai-sdk/gateway";
+import { createGoogleGenerativeAI, google } from "@ai-sdk/google";
+import { createOpenAI, openai } from "@ai-sdk/openai";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { createOpenRouter, openrouter } from "@openrouter/ai-sdk-provider";
+
+//#region src/agents/ModelFactory.ts
+const logger = getLogger("ModelFactory");
+const nimDefault = createOpenAICompatible({
+	name: "nim",
+	baseURL: "https://integrate.api.nvidia.com/v1",
+	headers: { Authorization: `Bearer ${process.env.NIM_API_KEY}` }
+});
+/**
+* Factory for creating AI SDK language models from configuration
+* Supports multiple providers and AI Gateway integration
+*/
+var ModelFactory = class ModelFactory {
+	/**
+	* Create a provider instance with custom configuration
+	* Returns a provider with at least languageModel method
+	*/
+	static createProvider(provider, config) {
+		switch (provider) {
+			case "anthropic": return createAnthropic(config);
+			case "openai": return createOpenAI(config);
+			case "google": return createGoogleGenerativeAI(config);
+			case "openrouter": return createOpenRouter(config);
+			case "gateway": return createGateway(config);
+			case "nim": return createOpenAICompatible({
+				name: "nim",
+				baseURL: "https://integrate.api.nvidia.com/v1",
+				headers: { Authorization: `Bearer ${process.env.NIM_API_KEY}` },
+				...config
+			});
+			case "custom": {
+				if (!config.baseURL && !config.baseUrl) throw new Error("Custom provider requires baseURL. Please provide it in providerOptions.baseURL or providerOptions.baseUrl");
+				const customConfig = {
+					name: "custom",
+					baseURL: config.baseURL || config.baseUrl,
+					headers: {
+						...process.env.CUSTOM_LLM_API_KEY && { Authorization: `Bearer ${process.env.CUSTOM_LLM_API_KEY}` },
+						...config.headers || {}
+					},
+					...config
+				};
+				logger.info({ config: {
+					baseURL: customConfig.baseURL,
+					hasApiKey: !!process.env.CUSTOM_LLM_API_KEY,
+					apiKeyPrefix: process.env.CUSTOM_LLM_API_KEY?.substring(0, 10) + "...",
+					headers: Object.keys(customConfig.headers || {})
+				} }, "Creating custom OpenAI-compatible provider");
+				return createOpenAICompatible(customConfig);
+			}
+			default: throw new Error(`Unsupported provider: ${provider}`);
+		}
+	}
+	/**
+	* Extract provider configuration from providerOptions
+	* Only includes settings that go to the provider constructor (baseURL, apiKey, etc.)
+	*/
+	static extractProviderConfig(providerOptions) {
+		if (!providerOptions) return {};
+		const providerConfig = {};
+		if (providerOptions.baseUrl || providerOptions.baseURL) providerConfig.baseURL = providerOptions.baseUrl || providerOptions.baseURL;
+		if (providerOptions.headers) providerConfig.headers = providerOptions.headers;
+		if (providerOptions.gateway) Object.assign(providerConfig, providerOptions.gateway);
+		if (providerOptions.nim) Object.assign(providerConfig, providerOptions.nim);
+		if (providerOptions.custom) Object.assign(providerConfig, providerOptions.custom);
+		return providerConfig;
+	}
+	/**
+	* Create a language model instance from configuration
+	* Throws error if no config provided - models must be configured at project level
+	*/
+	static createModel(config) {
+		if (!config?.model?.trim()) throw new Error("Model configuration is required. Please configure models at the project level.");
+		const modelSettings = config;
+		if (!modelSettings.model) throw new Error("Model configuration is required");
+		const modelString = modelSettings.model.trim();
+		const { provider, modelName } = ModelFactory.parseModelString(modelString);
+		logger.debug({
+			provider,
+			model: modelName,
+			fullModelString: modelSettings.model,
+			hasProviderOptions: !!modelSettings.providerOptions
+		}, "Creating language model from config");
+		const providerConfig = ModelFactory.extractProviderConfig(modelSettings.providerOptions);
+		if (Object.keys(providerConfig).length > 0) {
+			logger.info({ config: providerConfig }, `Applying custom ${provider} provider configuration`);
+			return ModelFactory.createProvider(provider, providerConfig).languageModel(modelName);
+		}
+		switch (provider) {
+			case "anthropic": return anthropic(modelName);
+			case "openai": return openai(modelName);
+			case "google": return google(modelName);
+			case "openrouter": return openrouter(modelName);
+			case "gateway": return gateway(modelName);
+			case "nim": return nimDefault(modelName);
+			case "custom": throw new Error("Custom provider requires configuration. Please provide baseURL in providerOptions.custom.baseURL or providerOptions.baseURL");
+			default: throw new Error(`Unsupported provider: ${provider}. Supported providers are: ${ModelFactory.BUILT_IN_PROVIDERS.join(", ")}. To access other models, use OpenRouter (openrouter/model-id), Vercel AI Gateway (gateway/model-id), NVIDIA NIM (nim/model-id), or Custom OpenAI-compatible (custom/model-id).`);
+		}
+	}
+	/**
+	* Built-in providers that have special handling
+	*/
+	static BUILT_IN_PROVIDERS = [
+		"anthropic",
+		"openai",
+		"google",
+		"openrouter",
+		"gateway",
+		"nim",
+		"custom"
+	];
+	/**
+	* Parse model string to extract provider and model name
+	* Examples: "anthropic/claude-sonnet-4" -> { provider: "anthropic", modelName: "claude-sonnet-4" }
+	*          "openrouter/anthropic/claude-sonnet-4" -> { provider: "openrouter", modelName: "anthropic/claude-sonnet-4" }
+	*          "claude-sonnet-4" -> { provider: "anthropic", modelName: "claude-sonnet-4" } (default to anthropic)
+	*/
+	static parseModelString(modelString) {
+		if (modelString.includes("/")) {
+			const [provider, ...modelParts] = modelString.split("/");
+			const normalizedProvider = provider.toLowerCase();
+			if (!ModelFactory.BUILT_IN_PROVIDERS.includes(normalizedProvider)) throw new Error(`Unsupported provider: ${normalizedProvider}. Supported providers are: ${ModelFactory.BUILT_IN_PROVIDERS.join(", ")}. To access other models, use OpenRouter (openrouter/model-id), Vercel AI Gateway (gateway/model-id), NVIDIA NIM (nim/model-id), or Custom OpenAI-compatible (custom/model-id).`);
+			return {
+				provider: normalizedProvider,
+				modelName: modelParts.join("/")
+			};
+		}
+		throw new Error(`No provider specified in model string: ${modelString}`);
+	}
+	/**
+	* Get generation parameters from provider options
+	* These are parameters that get passed to generateText/streamText calls
+	*/
+	static getGenerationParams(providerOptions) {
+		if (!providerOptions) return {};
+		const excludedKeys = [
+			"apiKey",
+			"baseURL",
+			"baseUrl",
+			"maxDuration",
+			"headers",
+			"gateway",
+			"nim",
+			"custom"
+		];
+		const params = {};
+		for (const [key, value] of Object.entries(providerOptions)) if (!excludedKeys.includes(key) && value !== void 0) params[key] = value;
+		return params;
+	}
+	/**
+	* Prepare complete generation configuration from model settings
+	* Returns model instance and generation parameters ready to spread into generateText/streamText
+	* Includes maxDuration if specified in provider options (in seconds, following Vercel standard)
+	*/
+	static prepareGenerationConfig(modelSettings) {
+		const modelString = modelSettings?.model?.trim();
+		const model = ModelFactory.createModel({
+			model: modelString,
+			providerOptions: modelSettings?.providerOptions
+		});
+		const generationParams = ModelFactory.getGenerationParams(modelSettings?.providerOptions);
+		const maxDuration = modelSettings?.providerOptions?.maxDuration;
+		return {
+			model,
+			...generationParams,
+			...maxDuration !== void 0 && { maxDuration }
+		};
+	}
+	/**
+	* Validate model settingsuration
+	* Basic validation only - let AI SDK handle parameter-specific validation
+	*/
+	static validateConfig(config) {
+		const errors = [];
+		if (!config.model) errors.push("Model name is required");
+		if (config.providerOptions) {
+			if (config.providerOptions.apiKey) errors.push("API keys should not be stored in provider options. Use environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY) or credential store instead.");
+			if (config.providerOptions.maxDuration !== void 0) {
+				const maxDuration = config.providerOptions.maxDuration;
+				if (typeof maxDuration !== "number" || maxDuration <= 0) errors.push("maxDuration must be a positive number (in seconds)");
+			}
+		}
+		return errors;
+	}
+};
+
+//#endregion
+export { ModelFactory };

package/dist/agents/SystemPromptBuilder.d.ts

@@ -0,0 +1,21 @@
+import { AssembleResult } from "../utils/token-estimator.js";
+import { VersionConfig } from "./types.js";
+
+//#region src/agents/SystemPromptBuilder.d.ts
+declare class SystemPromptBuilder<TConfig> {
+  private version;
+  private versionConfig;
+  private templates;
+  private loaded;
+  constructor(version: string, versionConfig: VersionConfig<TConfig>);
+  private loadTemplates;
+  /**
+   * Build the system prompt and return both the prompt string and token breakdown
+   */
+  buildSystemPrompt(config: TConfig): AssembleResult;
+  private validateTemplateVariables;
+  getLoadedTemplates(): string[];
+  isLoaded(): boolean;
+}
+//#endregion
+export { SystemPromptBuilder };

package/dist/agents/SystemPromptBuilder.js

@@ -0,0 +1,48 @@
+import { getLogger } from "../logger.js";
+
+//#region src/agents/SystemPromptBuilder.ts
+const logger = getLogger("SystemPromptBuilder");
+var SystemPromptBuilder = class {
+	templates = /* @__PURE__ */ new Map();
+	loaded = false;
+	constructor(version, versionConfig) {
+		this.version = version;
+		this.versionConfig = versionConfig;
+	}
+	loadTemplates() {
+		if (this.loaded) return;
+		try {
+			const loadedTemplates = this.versionConfig.loadTemplates();
+			for (const [name, content] of loadedTemplates) this.templates.set(name, content);
+			this.loaded = true;
+			logger.debug({
+				templateCount: this.templates.size,
+				version: this.version
+			}, `Loaded ${this.templates.size} templates for version ${this.version}`);
+		} catch (error) {
+			logger.error({ error }, `Failed to load templates for version ${this.version}`);
+			throw new Error(`Template loading failed: ${error}`);
+		}
+	}
+	/**
+	* Build the system prompt and return both the prompt string and token breakdown
+	*/
+	buildSystemPrompt(config) {
+		this.loadTemplates();
+		this.validateTemplateVariables(config);
+		return this.versionConfig.assemble(this.templates, config);
+	}
+	validateTemplateVariables(config) {
+		if (!config) throw new Error("Configuration object is required");
+		if (typeof config !== "object") throw new Error("Configuration must be an object");
+	}
+	getLoadedTemplates() {
+		return Array.from(this.templates.keys());
+	}
+	isLoaded() {
+		return this.loaded;
+	}
+};
+
+//#endregion
+export { SystemPromptBuilder };

package/dist/agents/ToolSessionManager.d.ts

@@ -0,0 +1,63 @@
+//#region src/agents/ToolSessionManager.d.ts
+interface ToolResultRecord {
+  toolCallId: string;
+  toolName: string;
+  args?: any;
+  result: any;
+  timestamp: number;
+}
+interface ToolSession {
+  sessionId: string;
+  tenantId: string;
+  projectId: string;
+  contextId: string;
+  taskId: string;
+  toolResults: Map<string, ToolResultRecord>;
+  createdAt: number;
+}
+/**
+ * Manages tool execution state during agent generation sessions.
+ * Allows tools to access previous tool call results within the same execution.
+ */
+declare class ToolSessionManager {
+  private static instance;
+  private sessions;
+  private constructor();
+  static getInstance(): ToolSessionManager;
+  /**
+   * Create a new tool session for an agent execution
+   */
+  createSession(tenantId: string, projectId: string, contextId: string, taskId: string): string;
+  /**
+   * Create a new tool session with a specific ID (for coordination with AgentSession)
+   */
+  createSessionWithId(sessionId: string, tenantId: string, projectId: string, contextId: string, taskId: string): string;
+  /**
+   * Ensure an agent-scoped session exists (idempotent)
+   * All agents in the same agent execution share this session
+   */
+  ensureAgentSession(sessionId: string, tenantId: string, projectId: string, contextId: string, taskId: string): string;
+  /**
+   * Record a tool result in the session
+   */
+  recordToolResult(sessionId: string, toolResult: ToolResultRecord): void;
+  /**
+   * Get a tool result by toolCallId within a session
+   */
+  getToolResult(sessionId: string, toolCallId: string): ToolResultRecord | undefined;
+  /**
+   * Get session info
+   */
+  getSession(sessionId: string): ToolSession | undefined;
+  /**
+   * Clean up a session after agent execution completes
+   */
+  endSession(sessionId: string): void;
+  /**
+   * Remove expired sessions to prevent memory leaks
+   */
+  private cleanupExpiredSessions;
+}
+declare const toolSessionManager: ToolSessionManager;
+//#endregion
+export { ToolResultRecord, ToolSession, ToolSessionManager, toolSessionManager };

package/dist/agents/ToolSessionManager.js

@@ -0,0 +1,146 @@
+import { getLogger } from "../logger.js";
+import { SESSION_CLEANUP_INTERVAL_MS, SESSION_TOOL_RESULT_CACHE_TIMEOUT_MS } from "../constants/execution-limits/index.js";
+import { generateId } from "@inkeep/agents-core";
+
+//#region src/agents/ToolSessionManager.ts
+const logger = getLogger("ToolSessionManager");
+/**
+* Manages tool execution state during agent generation sessions.
+* Allows tools to access previous tool call results within the same execution.
+*/
+var ToolSessionManager = class ToolSessionManager {
+	static instance;
+	sessions = /* @__PURE__ */ new Map();
+	constructor() {
+		setInterval(() => this.cleanupExpiredSessions(), SESSION_CLEANUP_INTERVAL_MS);
+	}
+	static getInstance() {
+		if (!ToolSessionManager.instance) ToolSessionManager.instance = new ToolSessionManager();
+		return ToolSessionManager.instance;
+	}
+	/**
+	* Create a new tool session for an agent execution
+	*/
+	createSession(tenantId, projectId, contextId, taskId) {
+		const sessionId = generateId();
+		return this.createSessionWithId(sessionId, tenantId, projectId, contextId, taskId);
+	}
+	/**
+	* Create a new tool session with a specific ID (for coordination with AgentSession)
+	*/
+	createSessionWithId(sessionId, tenantId, projectId, contextId, taskId) {
+		const session = {
+			sessionId,
+			tenantId,
+			projectId,
+			contextId,
+			taskId,
+			toolResults: /* @__PURE__ */ new Map(),
+			createdAt: Date.now()
+		};
+		this.sessions.set(sessionId, session);
+		logger.debug({
+			sessionId,
+			tenantId,
+			contextId,
+			taskId,
+			totalSessions: this.sessions.size
+		}, "Created tool session with ID");
+		return sessionId;
+	}
+	/**
+	* Ensure an agent-scoped session exists (idempotent)
+	* All agents in the same agent execution share this session
+	*/
+	ensureAgentSession(sessionId, tenantId, projectId, contextId, taskId) {
+		if (this.sessions.has(sessionId)) {
+			logger.debug({ sessionId }, "Agent session already exists, reusing");
+			return sessionId;
+		}
+		logger.debug({
+			sessionId,
+			tenantId,
+			contextId,
+			taskId
+		}, "Creating new agent-scoped tool session");
+		return this.createSessionWithId(sessionId, tenantId, projectId, contextId, taskId);
+	}
+	/**
+	* Record a tool result in the session
+	*/
+	recordToolResult(sessionId, toolResult) {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			logger.warn({
+				sessionId,
+				toolCallId: toolResult.toolCallId,
+				availableSessionIds: Array.from(this.sessions.keys()),
+				totalSessions: this.sessions.size
+			}, "Tool result recorded for unknown session");
+			return;
+		}
+		session.toolResults.set(toolResult.toolCallId, toolResult);
+		logger.debug({
+			sessionId,
+			toolCallId: toolResult.toolCallId,
+			toolName: toolResult.toolName
+		}, "Tool result recorded successfully");
+	}
+	/**
+	* Get a tool result by toolCallId within a session
+	*/
+	getToolResult(sessionId, toolCallId) {
+		const session = this.sessions.get(sessionId);
+		if (!session) {
+			logger.warn({
+				sessionId,
+				toolCallId,
+				availableSessionIds: Array.from(this.sessions.keys()),
+				totalSessions: this.sessions.size
+			}, "Requested tool result for unknown session");
+			return;
+		}
+		const result = session.toolResults.get(toolCallId);
+		if (!result) logger.warn({
+			sessionId,
+			toolCallId,
+			availableToolResultIds: Array.from(session.toolResults.keys()),
+			totalToolResults: session.toolResults.size
+		}, "Tool result not found");
+		else logger.debug({
+			sessionId,
+			toolCallId,
+			toolName: result.toolName
+		}, "Tool result found successfully");
+		return result;
+	}
+	/**
+	* Get session info
+	*/
+	getSession(sessionId) {
+		return this.sessions.get(sessionId);
+	}
+	/**
+	* Clean up a session after agent execution completes
+	*/
+	endSession(sessionId) {
+		if (this.sessions.get(sessionId)) this.sessions.delete(sessionId);
+	}
+	/**
+	* Remove expired sessions to prevent memory leaks
+	*/
+	cleanupExpiredSessions() {
+		const now = Date.now();
+		const expiredSessions = [];
+		for (const [sessionId, session] of this.sessions.entries()) if (now - session.createdAt > SESSION_TOOL_RESULT_CACHE_TIMEOUT_MS) expiredSessions.push(sessionId);
+		for (const sessionId of expiredSessions) {
+			this.sessions.delete(sessionId);
+			logger.debug({ sessionId }, "Cleaned up expired tool session");
+		}
+		if (expiredSessions.length > 0) logger.info({ expiredCount: expiredSessions.length }, "Cleaned up expired tool sessions");
+	}
+};
+const toolSessionManager = ToolSessionManager.getInstance();
+
+//#endregion
+export { ToolSessionManager, toolSessionManager };

package/dist/agents/generateTaskHandler.d.ts

@@ -0,0 +1,49 @@
+import { A2ATask, A2ATaskResult } from "../a2a/types.js";
+import { SandboxConfig } from "../types/execution-context.js";
+import { AgentConversationHistoryConfig, CredentialStoreRegistry, SubAgentApiSelect } from "@inkeep/agents-core";
+
+//#region src/agents/generateTaskHandler.d.ts
+
+/**
+ * Serializable configuration for creating task handlers
+ */
+interface TaskHandlerConfig {
+  tenantId: string;
+  projectId: string;
+  agentId: string;
+  subAgentId: string;
+  agentSchema: SubAgentApiSelect;
+  name: string;
+  baseUrl: string;
+  apiKey?: string;
+  description?: string;
+  contextConfigId?: string;
+  conversationHistoryConfig?: AgentConversationHistoryConfig;
+  sandboxConfig?: SandboxConfig;
+  /** User ID for user-scoped credential lookups (available when request is from authenticated user) */
+  userId?: string;
+}
+declare const createTaskHandler: (config: TaskHandlerConfig, credentialStoreRegistry?: CredentialStoreRegistry) => (task: A2ATask) => Promise<A2ATaskResult>;
+/**
+ * Serializes a TaskHandlerConfig to JSON
+ */
+declare const serializeTaskHandlerConfig: (config: TaskHandlerConfig) => string;
+/**
+ * Deserializes a TaskHandlerConfig from JSON
+ */
+declare const deserializeTaskHandlerConfig: (configJson: string) => TaskHandlerConfig;
+/**
+ * Creates a task handler configuration from agent data
+ */
+declare const createTaskHandlerConfig: (params: {
+  tenantId: string;
+  projectId: string;
+  agentId: string;
+  subAgentId: string;
+  baseUrl: string;
+  apiKey?: string;
+  sandboxConfig?: SandboxConfig;
+  userId?: string;
+}) => Promise<TaskHandlerConfig>;
+//#endregion
+export { TaskHandlerConfig, createTaskHandler, createTaskHandlerConfig, deserializeTaskHandlerConfig, serializeTaskHandlerConfig };