@inkeep/agents-sdk 0.39.4 → 0.40.0

package/dist/module-hosted-tool-manager.d.ts

@@ -0,0 +1,40 @@
+import { ChildProcess } from "node:child_process";
+
+//#region src/module-hosted-tool-manager.d.ts
+interface InlineToolFunction {
+  name: string;
+  description?: string;
+  execute: (params: any) => Promise<any>;
+  parameters?: Record<string, any>;
+}
+interface ModuleHostedToolServer {
+  toolFunction: InlineToolFunction;
+  process?: ChildProcess;
+  port: number;
+  serverUrl: string;
+  status: 'starting' | 'running' | 'stopped' | 'error';
+  pid?: number;
+  moduleFile: string;
+}
+declare class ModuleHostedToolManager {
+  private servers;
+  private portCounter;
+  private readonly baseDir;
+  private toolModules;
+  constructor();
+  deployInlineTool(toolFunction: InlineToolFunction): Promise<ModuleHostedToolServer>;
+  stopTool(toolName: string): Promise<void>;
+  getServer(toolName: string): ModuleHostedToolServer | undefined;
+  getAllServers(): ModuleHostedToolServer[];
+  private getToolId;
+  private getNextPort;
+  private generateModuleFiles;
+  private createToolModule;
+  private createMCPServerCode;
+  private startServer;
+  private handleFunctionExecution;
+  private waitForServerReady;
+}
+declare const moduleHostedToolManager: ModuleHostedToolManager;
+//#endregion
+export { InlineToolFunction, ModuleHostedToolManager, ModuleHostedToolServer, moduleHostedToolManager };

package/dist/module-hosted-tool-manager.js

@@ -0,0 +1,359 @@
+import { getLogger } from "@inkeep/agents-core";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+
+//#region src/module-hosted-tool-manager.ts
+const logger = getLogger("module-hosted-tool-manager");
+var ModuleHostedToolManager = class {
+	servers = /* @__PURE__ */ new Map();
+	portCounter = 3011;
+	baseDir;
+	toolModules = /* @__PURE__ */ new Map();
+	constructor() {
+		this.baseDir = join(process.cwd(), ".hosted-tools");
+		if (!existsSync(this.baseDir)) mkdirSync(this.baseDir, { recursive: true });
+	}
+	async deployInlineTool(toolFunction) {
+		const toolId = this.getToolId(toolFunction.name);
+		if (this.servers.has(toolId)) {
+			const existingServer = this.servers.get(toolId);
+			if (existingServer?.status === "running") {
+				logger.info({ toolId }, "Inline tool already deployed and running");
+				return existingServer;
+			}
+		}
+		const port = this.getNextPort();
+		const serverUrl = `http://localhost:${port}/mcp`;
+		this.toolModules.set(toolId, toolFunction);
+		const server = {
+			toolFunction,
+			port,
+			serverUrl,
+			status: "starting",
+			moduleFile: ""
+		};
+		this.servers.set(toolId, server);
+		try {
+			await this.generateModuleFiles(server);
+			await this.startServer(server);
+			await this.waitForServerReady(server);
+			server.status = "running";
+			logger.info({
+				toolId,
+				port,
+				serverUrl
+			}, "Inline tool deployed successfully");
+			return server;
+		} catch (error) {
+			server.status = "error";
+			logger.error({
+				toolId,
+				error: error instanceof Error ? error.message : "Unknown error"
+			}, "Failed to deploy inline tool");
+			throw error;
+		}
+	}
+	async stopTool(toolName) {
+		const toolId = this.getToolId(toolName);
+		const server = this.servers.get(toolId);
+		if (!server || !server.process) {
+			logger.warn({ toolId }, "Inline tool not found or not running");
+			return;
+		}
+		return new Promise((resolve) => {
+			server.process?.on("exit", () => {
+				server.status = "stopped";
+				server.process = void 0;
+				server.pid = void 0;
+				this.toolModules.delete(toolId);
+				logger.info({ toolId }, "Inline tool stopped successfully");
+				resolve();
+			});
+			server.process?.kill("SIGTERM");
+			setTimeout(() => {
+				if (server.process && !server.process.killed) server.process.kill("SIGKILL");
+			}, 5e3);
+		});
+	}
+	getServer(toolName) {
+		const toolId = this.getToolId(toolName);
+		return this.servers.get(toolId);
+	}
+	getAllServers() {
+		return Array.from(this.servers.values());
+	}
+	getToolId(name) {
+		return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+	}
+	getNextPort() {
+		return this.portCounter++;
+	}
+	async generateModuleFiles(server) {
+		const toolId = this.getToolId(server.toolFunction.name);
+		const serverDir = join(this.baseDir, toolId);
+		if (!existsSync(serverDir)) mkdirSync(serverDir, { recursive: true });
+		const toolModuleFile = join(serverDir, "tool-function.mjs");
+		writeFileSync(toolModuleFile, this.createToolModule(server.toolFunction), "utf8");
+		const serverFile = join(serverDir, "server.mjs");
+		writeFileSync(serverFile, this.createMCPServerCode(server, toolId), "utf8");
+		server.moduleFile = serverFile;
+		const packageJson = {
+			name: `hosted-tool-${toolId}`,
+			version: "1.0.0",
+			type: "module",
+			main: "server.mjs",
+			dependencies: {
+				"@modelcontextprotocol/sdk": "^1.12.1",
+				zod: "^3.25.31"
+			}
+		};
+		writeFileSync(join(serverDir, "package.json"), JSON.stringify(packageJson, null, 2), "utf8");
+		logger.info({
+			toolId,
+			serverFile,
+			toolModuleFile
+		}, "Generated module-based MCP server code");
+	}
+	createToolModule(toolFunction) {
+		return `// Auto-generated tool function module
+export const toolName = '${toolFunction.name}';
+export const toolDescription = '${toolFunction.description || ""}';
+
+// Re-export the tool function
+// Note: This approach requires the function to be passed through a registry
+export async function execute(params) {
+    // This will be resolved at runtime through the parent process communication
+    const result = await parentProcessExecute(params);
+    return result;
+}
+
+// Parameters schema (if provided)
+export const parameters = ${toolFunction.parameters ? JSON.stringify(toolFunction.parameters, null, 2) : "undefined"};
+`;
+	}
+	createMCPServerCode(server, toolId) {
+		return `#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp';
+import { z } from 'zod';
+import { createServer } from 'node:http';
+
+const server = new McpServer({
+    name: '${server.toolFunction.name}',
+    version: '1.0.0',
+}, { capabilities: { logging: {} } });
+
+// Parameter schema
+const parameterSchema = z.object({${server.toolFunction.parameters ? `${Object.keys(server.toolFunction.parameters).map((key) => `\n    ${key}: z.any()`).join(",")}\n` : ""}});
+
+// Communication with parent process for function execution
+let parentProcess = null;
+
+// Set up IPC communication
+process.on('message', (message) => {
+    if (message.type === 'function-result') {
+        // Handle function execution result
+        const { requestId, result, error } = message;
+        // Resolve the pending promise (this would need a proper promise registry)
+        handleFunctionResult(requestId, result, error);
+    }
+});
+
+const pendingRequests = new Map();
+let requestIdCounter = 0;
+
+async function executeToolFunction(params) {
+    return new Promise((resolve, reject) => {
+        const requestId = ++requestIdCounter;
+        pendingRequests.set(requestId, { resolve, reject });
+        
+        // Send execution request to parent process
+        process.send({
+            type: 'execute-function',
+            requestId,
+            toolName: '${server.toolFunction.name}',
+            params
+        });
+        
+        // Timeout after 30 seconds
+        setTimeout(() => {
+            if (pendingRequests.has(requestId)) {
+                pendingRequests.delete(requestId);
+                reject(new Error('Function execution timeout'));
+            }
+        }, 30000);
+    });
+}
+
+function handleFunctionResult(requestId, result, error) {
+    const pending = pendingRequests.get(requestId);
+    if (pending) {
+        pendingRequests.delete(requestId);
+        if (error) {
+            pending.reject(new Error(error));
+        } else {
+            pending.resolve(result);
+        }
+    }
+}
+
+// Register the tool
+server.tool('${toolId}', '${server.toolFunction.description || ""}', parameterSchema.shape, async (params) => {
+    try {
+        const result = await executeToolFunction(params);
+        return {
+            content: [{ 
+                type: 'text', 
+                text: typeof result === 'string' ? result : JSON.stringify(result) 
+            }]
+        };
+    } catch (error) {
+        return {
+            content: [{ 
+                type: 'text', 
+                text: \`Error executing tool: \${error instanceof Error ? error.message : 'Unknown error'}\`
+            }],
+            isError: true
+        };
+    }
+});
+
+// Create HTTP server
+const httpServer = createServer();
+const transport = new StreamableHTTPServerTransport({});
+
+httpServer.on('request', async (req, res) => {
+    if (req.url === '/mcp' && req.method === 'POST') {
+        let body = '';
+        req.on('data', chunk => body += chunk);
+        req.on('end', async () => {
+            try {
+                const jsonBody = JSON.parse(body);
+                await transport.handleRequest(req, res, jsonBody);
+            } catch (error) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            }
+        });
+    } else if (req.url === '/health' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'healthy', tool: '${server.toolFunction.name}' }));
+    } else {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    }
+});
+
+// Start the server
+await server.connect(transport);
+httpServer.listen(${server.port}, () => {
+    console.log(\`MCP tool server '${server.toolFunction.name}' listening on port ${server.port}\`);
+    
+    // Notify parent that server is ready
+    if (process.send) {
+        process.send({ type: 'server-ready' });
+    }
+});
+
+process.on('SIGTERM', () => {
+    httpServer.close(() => {
+        console.log('Server stopped');
+        process.exit(0);
+    });
+});
+`;
+	}
+	async startServer(server) {
+		const toolId = this.getToolId(server.toolFunction.name);
+		const serverDir = join(this.baseDir, toolId);
+		const serverFile = server.moduleFile;
+		return new Promise((resolve, reject) => {
+			const childProcess = spawn("node", [serverFile], {
+				cwd: serverDir,
+				stdio: [
+					"ignore",
+					"pipe",
+					"pipe",
+					"ipc"
+				],
+				detached: false
+			});
+			server.process = childProcess;
+			server.pid = childProcess.pid;
+			childProcess.on("message", (message) => {
+				if (message.type === "execute-function") this.handleFunctionExecution(message, childProcess);
+				else if (message.type === "server-ready") logger.info({ toolId }, "Tool server reported ready via IPC");
+			});
+			childProcess.stdout?.on("data", (data) => {
+				logger.info({ toolId }, `Tool server stdout: ${data.toString().trim()}`);
+			});
+			childProcess.stderr?.on("data", (data) => {
+				logger.error({ toolId }, `Tool server stderr: ${data.toString().trim()}`);
+			});
+			childProcess.on("error", (error) => {
+				logger.error({
+					toolId,
+					error: error.message
+				}, "Failed to start tool server");
+				reject(error);
+			});
+			childProcess.on("exit", (code, signal) => {
+				logger.info({
+					toolId,
+					code,
+					signal
+				}, "Tool server process exited");
+				server.status = "stopped";
+				server.process = void 0;
+				server.pid = void 0;
+			});
+			setTimeout(() => {
+				if (childProcess.pid) resolve();
+				else reject(/* @__PURE__ */ new Error("Failed to start server process"));
+			}, 1e3);
+		});
+	}
+	async handleFunctionExecution(message, childProcess) {
+		const { requestId, toolName, params } = message;
+		const toolFunction = this.toolModules.get(this.getToolId(toolName));
+		if (!toolFunction) {
+			childProcess.send({
+				type: "function-result",
+				requestId,
+				error: `Tool function not found: ${toolName}`
+			});
+			return;
+		}
+		try {
+			const result = await toolFunction.execute(params);
+			childProcess.send({
+				type: "function-result",
+				requestId,
+				result
+			});
+		} catch (error) {
+			childProcess.send({
+				type: "function-result",
+				requestId,
+				error: error instanceof Error ? error.message : "Unknown error"
+			});
+		}
+	}
+	async waitForServerReady(server, maxRetries = 10) {
+		for (let i = 0; i < maxRetries; i++) {
+			try {
+				if ((await fetch(`http://localhost:${server.port}/health`)).ok) {
+					logger.info({ toolId: this.getToolId(server.toolFunction.name) }, "Server health check passed");
+					return;
+				}
+			} catch (_error) {}
+			await new Promise((resolve) => setTimeout(resolve, 500));
+		}
+		throw new Error(`Server failed to become ready after ${maxRetries} attempts`);
+	}
+};
+const moduleHostedToolManager = new ModuleHostedToolManager();
+
+//#endregion
+export { ModuleHostedToolManager, moduleHostedToolManager };

package/dist/project.d.ts

@@ -0,0 +1,214 @@
+import { ArtifactComponent } from "./artifact-component.js";
+import { Tool } from "./tool.js";
+import { DataComponent } from "./data-component.js";
+import { ExternalAgent } from "./external-agent.js";
+import { ModelSettings } from "./types.js";
+import { Agent } from "./agent.js";
+import { CredentialReferenceApiInsert, FullProjectDefinition, StopWhen } from "@inkeep/agents-core";
+
+//#region src/project.d.ts
+
+/**
+ * Project configuration interface for the SDK
+ */
+interface ProjectConfig {
+  id: string;
+  name: string;
+  description?: string;
+  models?: {
+    base?: ModelSettings;
+    structuredOutput?: ModelSettings;
+    summarizer?: ModelSettings;
+  };
+  stopWhen?: StopWhen;
+  agents?: () => Agent[];
+  tools?: () => Tool[];
+  externalAgents?: () => ExternalAgent[];
+  dataComponents?: () => DataComponent[];
+  artifactComponents?: () => ArtifactComponent[];
+  credentialReferences?: () => CredentialReferenceApiInsert[];
+}
+/**
+ * Project interface for operations
+ */
+interface ProjectInterface {
+  init(): Promise<void>;
+  setConfig(tenantId: string, apiUrl: string): void;
+  getId(): string;
+  getName(): string;
+  getDescription(): string | undefined;
+  getTenantId(): string;
+  getModels(): ProjectConfig['models'];
+  getStopWhen(): ProjectConfig['stopWhen'];
+  getAgents(): Agent[];
+  addAgent(agent: Agent): void;
+  removeAgent(id: string): boolean;
+  getStats(): {
+    projectId: string;
+    tenantId: string;
+    agentCount: number;
+    initialized: boolean;
+  };
+  validate(): {
+    valid: boolean;
+    errors: string[];
+  };
+}
+/**
+ * Project class for managing agent projects
+ *
+ * Projects are the top-level organizational unit that contains Agents, Sub Agents, and shared configurations.
+ * They provide model inheritance and execution limits that cascade down to Agents and Sub Agents.
+ *
+ * @example
+ * ```typescript
+ * const myProject = new Project({
+ *   id: 'customer-support-project',
+ *   name: 'Customer Support System',
+ *   description: 'Multi-agent customer support system',
+ *   models: {
+ *     base: { model: 'gpt-4.1-mini' },
+ *     structuredOutput: { model: 'gpt-4.1' }
+ *   },
+ *   stopWhen: {
+ *     transferCountIs: 10,
+ *     stepCountIs: 50
+ *   }
+ * });
+ *
+ * await myProject.init();
+ * ```
+ */
+declare class Project implements ProjectInterface {
+  readonly __type: "project";
+  private projectId;
+  private projectName;
+  private projectDescription?;
+  private tenantId;
+  private baseURL;
+  private apiKey?;
+  private initialized;
+  private models?;
+  private stopWhen?;
+  private agents;
+  private agentMap;
+  private credentialReferences?;
+  private projectTools;
+  private projectDataComponents;
+  private projectArtifactComponents;
+  private projectExternalAgents;
+  private externalAgentMap;
+  constructor(config: ProjectConfig);
+  /**
+   * Set or update the configuration (tenantId and apiUrl)
+   * This is used by the CLI to inject configuration from inkeep.config.ts
+   */
+  setConfig(tenantId: string, apiUrl: string, models?: ProjectConfig['models'], apiKey?: string): void;
+  /**
+   * Set credential references for the project
+   * This is used by the CLI to inject environment-specific credentials
+   */
+  setCredentials(credentials: Record<string, CredentialReferenceApiInsert>): void;
+  /**
+   * Initialize the project and create/update it in the backend using full project approach
+   */
+  init(): Promise<void>;
+  /**
+   * Get the project ID
+   */
+  getId(): string;
+  /**
+   * Get the project name
+   */
+  getName(): string;
+  /**
+   * Get the project description
+   */
+  getDescription(): string | undefined;
+  /**
+   * Get the tenant ID
+   */
+  getTenantId(): string;
+  /**
+   * Get the project's model configuration
+   */
+  getModels(): ProjectConfig['models'];
+  /**
+   * Set the project's model configuration
+   */
+  setModels(models: ProjectConfig['models']): void;
+  /**
+   * Get the project's stopWhen configuration
+   */
+  getStopWhen(): ProjectConfig['stopWhen'];
+  /**
+   * Set the project's stopWhen configuration
+   */
+  setStopWhen(stopWhen: ProjectConfig['stopWhen']): void;
+  /**
+   * Get credential tracking information
+   */
+  getCredentialTracking(): Promise<{
+    credentials: Record<string, any>;
+    usage: Record<string, Array<{
+      type: string;
+      id: string;
+      agentId?: string;
+    }>>;
+  }>;
+  getFullDefinition(): Promise<FullProjectDefinition>;
+  /**
+   * Get all agent in the project
+   */
+  getAgents(): Agent[];
+  /**
+   * Get all external agents in the project
+   */
+  getExternalAgents(): ExternalAgent[];
+  /**
+   * Get an external agent by ID
+   */
+  getExternalAgent(id: string): ExternalAgent | undefined;
+  /**
+   * Add an external agent to the project
+   */
+  addExternalAgent(externalAgent: ExternalAgent): void;
+  /**
+   * Remove an external agent from the project
+   */
+  removeExternalAgent(id: string): boolean;
+  /**
+   * Get an agent by ID
+   */
+  getAgent(id: string): Agent | undefined;
+  /**
+   * Add an agent to the project
+   */
+  addAgent(agent: Agent): void;
+  /**
+   * Remove an agent from the project
+   */
+  removeAgent(id: string): boolean;
+  /**
+   * Get project statistics
+   */
+  getStats(): {
+    projectId: string;
+    tenantId: string;
+    agentCount: number;
+    initialized: boolean;
+  };
+  /**
+   * Validate the project configuration
+   */
+  validate(): {
+    valid: boolean;
+    errors: string[];
+  };
+  /**
+   * Convert the Project to FullProjectDefinition format
+   */
+  private toFullProjectDefinition;
+}
+//#endregion
+export { Project, ProjectConfig, ProjectInterface };