@inkeep/agents-run-api 0.1.0

package/dist/agents/ModelFactory.d.ts

@@ -0,0 +1,62 @@
+import type { LanguageModel } from 'ai';
+export interface ModelSettings {
+    model?: string;
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Factory for creating AI SDK language models from configuration
+ * Supports multiple providers and AI Gateway integration
+ */
+export declare class ModelFactory {
+    /**
+     * Default model settingsuration to use when no model settings is provided
+     * Uses provider defaults for all parameters
+     */
+    private static readonly DEFAULT_MODEL_CONFIG;
+    /**
+     * Create a language model instance from configuration
+     * Falls back to default Anthropic model if no config provided
+     */
+    static createModel(config?: ModelSettings | null): LanguageModel;
+    /**
+     * Supported providers for security validation
+     */
+    private static readonly SUPPORTED_PROVIDERS;
+    /**
+     * Parse model string to extract provider and model name
+     * Examples: "anthropic/claude-4-sonnet" -> { provider: "anthropic", modelName: "claude-4-sonnet" }
+     *          "claude-4-sonnet" -> { provider: "anthropic", modelName: "claude-4-sonnet" } (default to anthropic)
+     */
+    static parseModelString(modelString: string): {
+        provider: string;
+        modelName: string;
+    };
+    /**
+     * Create an Anthropic model instance
+     */
+    private static createAnthropicModel;
+    /**
+     * Create an OpenAI model instance
+     */
+    private static createOpenAIModel;
+    /**
+     * 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[];
+}
+//# sourceMappingURL=ModelFactory.d.ts.map

package/dist/agents/ModelFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelFactory.d.ts","sourceRoot":"","sources":["../../src/agents/ModelFactory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAKxC,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,oBAAoB,CAE1C;IAEF;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,GAAG,aAAa;IAiDhE;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAoC;IAE/E;;;;OAIG;IACH,MAAM,CAAC,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IA+BrF;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAkCnC;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAgChC;;;OAGG;IACH,MAAM,CAAC,mBAAmB,CACxB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB1B;;;;OAIG;IACH,MAAM,CAAC,uBAAuB,CAAC,aAAa,CAAC,EAAE,aAAa,GAAG;QAAE,KAAK,EAAE,aAAa,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAwBvI;;;OAGG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,EAAE;CA4BvD"}

package/dist/agents/ModelFactory.js

@@ -0,0 +1,208 @@
+import { anthropic, createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI, openai } from '@ai-sdk/openai';
+import { getLogger } from '../logger.js';
+const logger = getLogger('ModelFactory');
+/**
+ * Factory for creating AI SDK language models from configuration
+ * Supports multiple providers and AI Gateway integration
+ */
+export class ModelFactory {
+    /**
+     * Default model settingsuration to use when no model settings is provided
+     * Uses provider defaults for all parameters
+     */
+    static DEFAULT_MODEL_CONFIG = {
+        model: 'anthropic/claude-4-sonnet-20250514',
+    };
+    /**
+     * Create a language model instance from configuration
+     * Falls back to default Anthropic model if no config provided
+     */
+    static createModel(config) {
+        // Use default config if none provided
+        const modelSettings = config || ModelFactory.DEFAULT_MODEL_CONFIG;
+        // Extract provider from model string (e.g., "anthropic/claude-4-sonnet" -> "anthropic")
+        // Handle empty strings by falling back to default
+        const modelString = (modelSettings.model?.trim()) || ModelFactory.DEFAULT_MODEL_CONFIG.model;
+        const { provider, modelName } = ModelFactory.parseModelString(modelString);
+        logger.debug({
+            provider,
+            model: modelName,
+            fullModelString: modelSettings.model,
+            hasProviderOptions: !!modelSettings.providerOptions,
+        }, 'Creating language model from config');
+        try {
+            switch (provider) {
+                case 'anthropic':
+                    return ModelFactory.createAnthropicModel(modelName, modelSettings.providerOptions);
+                case 'openai':
+                    return ModelFactory.createOpenAIModel(modelName, modelSettings.providerOptions);
+                default:
+                    logger.warn({ provider, modelName }, 'Unknown or unsupported provider, falling back to default Anthropic model');
+                    return ModelFactory.createAnthropicModel('claude-4-sonnet-20250514');
+            }
+        }
+        catch (error) {
+            logger.error({
+                provider,
+                model: modelName,
+                error: error instanceof Error ? error.message : 'Unknown error',
+            }, 'Failed to create model, falling back to default');
+            // Fall back to default model if creation fails
+            return ModelFactory.createAnthropicModel('claude-4-sonnet-20250514');
+        }
+    }
+    /**
+     * Supported providers for security validation
+     */
+    static SUPPORTED_PROVIDERS = ['anthropic', 'openai'];
+    /**
+     * Parse model string to extract provider and model name
+     * Examples: "anthropic/claude-4-sonnet" -> { provider: "anthropic", modelName: "claude-4-sonnet" }
+     *          "claude-4-sonnet" -> { provider: "anthropic", modelName: "claude-4-sonnet" } (default to anthropic)
+     */
+    static parseModelString(modelString) {
+        // Handle format like "provider/model-name"
+        if (modelString.includes('/')) {
+            const [provider, ...modelParts] = modelString.split('/');
+            const normalizedProvider = provider.toLowerCase();
+            // Validate provider is supported
+            if (!ModelFactory.SUPPORTED_PROVIDERS.includes(normalizedProvider)) {
+                logger.warn({ provider: normalizedProvider, modelName: modelParts.join('/') }, 'Unsupported provider detected, falling back to anthropic');
+                return {
+                    provider: 'anthropic',
+                    modelName: modelParts.join('/'),
+                };
+            }
+            return {
+                provider: normalizedProvider,
+                modelName: modelParts.join('/'), // In case model name has slashes
+            };
+        }
+        // Default to anthropic if no provider specified
+        return {
+            provider: 'anthropic',
+            modelName: modelString,
+        };
+    }
+    /**
+     * Create an Anthropic model instance
+     */
+    static createAnthropicModel(modelName, providerOptions) {
+        const anthropicConfig = {};
+        // Extract provider configuration (baseURL, etc.)
+        // Note: API keys should be provided via environment variables, not in configuration
+        if (providerOptions?.baseUrl || providerOptions?.baseURL) {
+            anthropicConfig.baseURL = providerOptions.baseUrl || providerOptions.baseURL;
+        }
+        // Handle AI Gateway configuration if present
+        if (providerOptions?.gateway) {
+            logger.info({ gateway: providerOptions.gateway }, 'Setting up AI Gateway for Anthropic model');
+            // AI Gateway configuration would go here
+            // This depends on the specific gateway implementation
+            Object.assign(anthropicConfig, providerOptions.gateway);
+        }
+        // For AI SDK v5, model parameters like temperature are passed to generateText/streamText,
+        // not to the model constructor. Only provider config (apiKey, baseURL) goes to the provider.
+        if (Object.keys(anthropicConfig).length > 0) {
+            logger.info({ config: anthropicConfig }, 'Applying custom Anthropic provider configuration');
+            // In AI SDK v5, use createAnthropic for custom config
+            const provider = createAnthropic(anthropicConfig);
+            return provider(modelName);
+        }
+        return anthropic(modelName);
+    }
+    /**
+     * Create an OpenAI model instance
+     */
+    static createOpenAIModel(modelName, providerOptions) {
+        const openaiConfig = {};
+        // Extract provider configuration (baseURL, etc.)
+        // Note: API keys should be provided via environment variables, not in configuration
+        if (providerOptions?.baseUrl || providerOptions?.baseURL) {
+            openaiConfig.baseURL = providerOptions.baseUrl || providerOptions.baseURL;
+        }
+        // Handle AI Gateway configuration if present
+        if (providerOptions?.gateway) {
+            logger.info({ gateway: providerOptions.gateway }, 'Setting up AI Gateway for OpenAI model');
+            Object.assign(openaiConfig, providerOptions.gateway);
+        }
+        // For AI SDK v5, model parameters like temperature are passed to generateText/streamText,
+        // not to the model constructor. Only provider config (apiKey, baseURL) goes to the provider.
+        if (Object.keys(openaiConfig).length > 0) {
+            logger.info({ config: openaiConfig }, 'Applying custom OpenAI provider configuration');
+            // In AI SDK v5, use createOpenAI for custom config
+            const provider = createOpenAI(openaiConfig);
+            return provider(modelName);
+        }
+        return openai(modelName);
+    }
+    /**
+     * Get generation parameters from provider options
+     * These are parameters that get passed to generateText/streamText calls
+     */
+    static getGenerationParams(providerOptions) {
+        if (!providerOptions) {
+            return {};
+        }
+        // Exclude provider config items (these go to createProvider, not generateText/streamText)
+        // Also exclude maxDuration as it's handled separately for timeouts
+        const excludedKeys = ['apiKey', 'baseURL', 'baseUrl', 'maxDuration'];
+        // Return all config except excluded items
+        const params = {};
+        for (const [key, value] of Object.entries(providerOptions)) {
+            if (!excludedKeys.includes(key) && value !== undefined) {
+                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()) || 'anthropic/claude-4-sonnet-20250514';
+        // Create the model instance
+        const model = ModelFactory.createModel({
+            model: modelString,
+            providerOptions: modelSettings?.providerOptions,
+        });
+        // Get generation parameters (excludes maxDuration)
+        const generationParams = ModelFactory.getGenerationParams(modelSettings?.providerOptions);
+        // Extract maxDuration if present (Vercel standard, in seconds)
+        const maxDuration = modelSettings?.providerOptions?.maxDuration;
+        return {
+            model,
+            ...generationParams,
+            ...(maxDuration !== undefined && { 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');
+        }
+        // Validate provider options structure if present
+        if (config.providerOptions) {
+            // Security validation: Check for API keys in configuration
+            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.');
+            }
+            // Validate maxDuration if present
+            if (config.providerOptions.maxDuration !== undefined) {
+                const maxDuration = config.providerOptions.maxDuration;
+                if (typeof maxDuration !== 'number' || maxDuration <= 0) {
+                    errors.push('maxDuration must be a positive number (in seconds)');
+                }
+            }
+        }
+        return errors;
+    }
+}

package/dist/agents/SystemPromptBuilder.d.ts

@@ -0,0 +1,14 @@
+import type { VersionConfig } from './types.js';
+export declare class SystemPromptBuilder<TConfig> {
+    private version;
+    private versionConfig;
+    private templates;
+    private loaded;
+    constructor(version: string, versionConfig: VersionConfig<TConfig>);
+    private loadTemplates;
+    buildSystemPrompt(config: TConfig): Promise<string>;
+    private validateTemplateVariables;
+    getLoadedTemplates(): string[];
+    isLoaded(): boolean;
+}
+//# sourceMappingURL=SystemPromptBuilder.d.ts.map

package/dist/agents/SystemPromptBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemPromptBuilder.d.ts","sourceRoot":"","sources":["../../src/agents/SystemPromptBuilder.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,qBAAa,mBAAmB,CAAC,OAAO;IAKpC,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,aAAa;IALvB,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,MAAM,CAAS;gBAGb,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,aAAa,CAAC,OAAO,CAAC;YAGjC,aAAa;IA6Bd,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAUhE,OAAO,CAAC,yBAAyB;IAW1B,kBAAkB,IAAI,MAAM,EAAE;IAI9B,QAAQ,IAAI,OAAO;CAG3B"}

package/dist/agents/SystemPromptBuilder.js

@@ -0,0 +1,62 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getLogger } from '../logger.js';
+const logger = getLogger('SystemPromptBuilder');
+export class SystemPromptBuilder {
+    version;
+    versionConfig;
+    templates = new Map();
+    loaded = false;
+    constructor(version, versionConfig) {
+        this.version = version;
+        this.versionConfig = versionConfig;
+    }
+    async loadTemplates() {
+        if (this.loaded)
+            return;
+        try {
+            const currentDir = dirname(fileURLToPath(import.meta.url));
+            const templatesDir = join(currentDir, '..', 'templates', this.version);
+            // Load all required template files for this version
+            const templatePromises = this.versionConfig.templateFiles.map(async (filename) => {
+                const filePath = join(templatesDir, filename);
+                const content = await readFile(filePath, 'utf-8');
+                const templateName = filename.replace('.xml', ''); // Remove extension for key
+                return [templateName, content];
+            });
+            const templateEntries = await Promise.all(templatePromises);
+            for (const [name, content] of templateEntries) {
+                this.templates.set(name, content);
+            }
+            this.loaded = true;
+            logger.debug(`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}`);
+        }
+    }
+    async buildSystemPrompt(config) {
+        await this.loadTemplates();
+        // Validate that all required template variables are present
+        this.validateTemplateVariables(config);
+        // Let the version config handle assembly
+        return this.versionConfig.assemble(this.templates, config);
+    }
+    validateTemplateVariables(config) {
+        if (!config) {
+            throw new Error('Configuration object is required');
+        }
+        // Basic validation - version configs can add their own validation
+        if (typeof config !== 'object') {
+            throw new Error('Configuration must be an object');
+        }
+    }
+    getLoadedTemplates() {
+        return Array.from(this.templates.keys());
+    }
+    isLoaded() {
+        return this.loaded;
+    }
+}

package/dist/agents/ToolSessionManager.d.ts

@@ -0,0 +1,61 @@
+export interface ToolResultRecord {
+    toolCallId: string;
+    toolName: string;
+    args?: any;
+    result: any;
+    timestamp: number;
+}
+export 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.
+ */
+export declare class ToolSessionManager {
+    private static instance;
+    private sessions;
+    private readonly SESSION_TIMEOUT;
+    private constructor();
+    static getInstance(): ToolSessionManager;
+    /**
+     * Create a new tool session for an agent execution
+     */
+    createSession(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;
+    /**
+     * Get detailed session information for logging
+     */
+    private getSessionDetails;
+    /**
+     * Get summary of all sessions for logging
+     */
+    private getSessionSummary;
+}
+export declare const toolSessionManager: ToolSessionManager;
+//# sourceMappingURL=ToolSessionManager.d.ts.map

package/dist/agents/ToolSessionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolSessionManager.d.ts","sourceRoot":"","sources":["../../src/agents/ToolSessionManager.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,MAAM,EAAE,GAAG,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IAEjD,OAAO;IAKP,MAAM,CAAC,WAAW,IAAI,kBAAkB;IAOxC;;OAEG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAiB7F;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAavE;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAsBlF;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAItD;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAOnC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAoB9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmBzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;CAa1B;AAGD,eAAO,MAAM,kBAAkB,oBAAmC,CAAC"}

package/dist/agents/ToolSessionManager.js

@@ -0,0 +1,143 @@
+import { nanoid } from 'nanoid';
+import { getLogger } from '../logger.js';
+const logger = getLogger('ToolSessionManager');
+/**
+ * Manages tool execution state during agent generation sessions.
+ * Allows tools to access previous tool call results within the same execution.
+ */
+export class ToolSessionManager {
+    static instance;
+    sessions = new Map();
+    SESSION_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+    constructor() {
+        // Cleanup expired sessions every minute
+        setInterval(() => this.cleanupExpiredSessions(), 60_000);
+    }
+    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 = nanoid();
+        const session = {
+            sessionId,
+            tenantId,
+            projectId,
+            contextId,
+            taskId,
+            toolResults: new Map(),
+            createdAt: Date.now(),
+        };
+        this.sessions.set(sessionId, session);
+        logger.debug({ sessionId, tenantId, contextId, taskId }, 'Created tool session');
+        return sessionId;
+    }
+    /**
+     * Record a tool result in the session
+     */
+    recordToolResult(sessionId, toolResult) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            logger.warn({ sessionId, toolCallId: toolResult.toolCallId }, 'Tool result recorded for unknown session');
+            return;
+        }
+        session.toolResults.set(toolResult.toolCallId, toolResult);
+    }
+    /**
+     * Get a tool result by toolCallId within a session
+     */
+    getToolResult(sessionId, toolCallId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            logger.warn({ sessionId, toolCallId }, 'Requested tool result for unknown session');
+            return undefined;
+        }
+        const result = session.toolResults.get(toolCallId);
+        if (!result) {
+            logger.warn({
+                sessionId,
+                toolCallId,
+                availableToolResultIds: Array.from(session.toolResults.keys()),
+            }, 'Tool result not found');
+        }
+        return result;
+    }
+    /**
+     * Get session info
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    /**
+     * Clean up a session after agent execution completes
+     */
+    endSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session) {
+            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 > this.SESSION_TIMEOUT) {
+                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');
+        }
+    }
+    /**
+     * Get detailed session information for logging
+     */
+    getSessionDetails(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return null;
+        return {
+            tenantId: session.tenantId,
+            contextId: session.contextId,
+            taskId: session.taskId,
+            createdAt: new Date(session.createdAt).toISOString(),
+            ageMs: Date.now() - session.createdAt,
+            toolResults: Array.from(session.toolResults.entries()).map(([id, result]) => ({
+                id,
+                toolName: result.toolName,
+                timestamp: new Date(result.timestamp).toISOString(),
+                hasResult: !!result.result,
+            })),
+        };
+    }
+    /**
+     * Get summary of all sessions for logging
+     */
+    getSessionSummary() {
+        return {
+            totalSessions: this.sessions.size,
+            sessions: Array.from(this.sessions.entries()).map(([id, session]) => ({
+                sessionId: id,
+                tenantId: session.tenantId,
+                contextId: session.contextId,
+                taskId: session.taskId,
+                toolResultCount: session.toolResults.size,
+                ageMs: Date.now() - session.createdAt,
+            })),
+        };
+    }
+}
+// Export singleton instance
+export const toolSessionManager = ToolSessionManager.getInstance();

package/dist/agents/artifactTools.d.ts

@@ -0,0 +1,30 @@
+import type { ArtifactComponentApiInsert } from '@inkeep/agents-core';
+export declare function createSaveToolResultTool(sessionId?: string, streamRequestId?: string, // For GraphSession recording
+agentId?: string, artifactComponents?: ArtifactComponentApiInsert[]): import("ai").Tool<{
+    toolCallId: string;
+    baseSelector: string;
+    propSelectors: any;
+}, {
+    saved: boolean;
+    error: string;
+    artifactIds: never[];
+    warnings: never[];
+    artifacts?: undefined;
+} | {
+    saved: boolean;
+    artifacts: {
+        artifactId: any;
+        taskId: any;
+        summaryData: any;
+    }[];
+    warnings: string[];
+    error?: undefined;
+    artifactIds?: undefined;
+} | {
+    saved: boolean;
+    error: string;
+    warnings: never[];
+    artifactIds?: undefined;
+    artifacts?: undefined;
+}>;
+//# sourceMappingURL=artifactTools.d.ts.map

package/dist/agents/artifactTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifactTools.d.ts","sourceRoot":"","sources":["../../src/agents/artifactTools.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AA+NtE,wBAAgB,wBAAwB,CACtC,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,6BAA6B;AACvD,OAAO,CAAC,EAAE,MAAM,EAChB,kBAAkB,CAAC,EAAE,0BAA0B,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;GAkUlD"}