@multiplayer-app/ai-agent-node 0.0.1

package/src/helpers/AIHelper.ts

@@ -0,0 +1,353 @@
+import { AdditionalContext, AgentAttachmentType, AgentConfig, AgentMessage, MessageRole } from "@multiplayer-app/ai-agent-types";
+import {ModelMessage, ToolModelMessage, ToolResultPart, streamText, UserContent} from "ai";
+import { AIService, GenerateTextOptions, StreamTextOptions } from "../services";
+import { ModelStore } from "../store";
+import { logger } from "../libs/logger";
+import { FilePart, ImagePart, ReasoningPart, TextPart, ToolCallPart} from "@ai-sdk/provider-utils";
+import { ConfigStore } from "../store";
+import { isImage, prepareImageForVisionAPI, extractTextFromDocument } from "./FileHelper";
+
+
+export class AIHelper {
+    private static async convertUserMessage(msg: Pick<AgentMessage, 'attachments' | 'content'>, ignoreFileAttachments: boolean): Promise<Array<TextPart | ImagePart | FilePart>> {
+        const userContent: UserContent = [{
+            type: "text",
+            text: msg.content
+        }];
+        const atts = msg.attachments ?? [];
+        if (!atts.length) {
+            return userContent;
+        }
+
+        const lines: string[] = [];
+
+        for (const att of atts) {
+            if (att.type !== AgentAttachmentType.Context) {
+                if (ignoreFileAttachments) {
+                    continue;
+                }
+                if (isImage(att)) {
+                    const image = await prepareImageForVisionAPI(att)
+                    if(image) {
+                        userContent.push({
+                            type: "image",
+                            image: image.image_url.url,
+                            mediaType: att.mimeType as string,
+                        })
+                    }
+                } else {
+                    const fileText = await extractTextFromDocument(att)
+                    if(fileText) {
+                        userContent.push({
+                            type: "text",
+                            text: `${att.type}: ${att.name}(${att.mimeType})\n ${fileText}`
+                        })
+                    }
+
+                }
+                continue;
+            }
+
+            const md = att.metadata as any;
+            const kind = typeof md?.kind === 'string' ? md.kind : 'unknown';
+            lines.push(`- context:${kind}: ${att.name}`);
+
+            if (kind === 'webSnippet') {
+                const url = typeof md?.source?.url === 'string' ? md.source.url : att.url;
+                const title = typeof md?.title === 'string' ? md.title : undefined;
+                const selectedText = typeof md?.selectedText === 'string' ? md.selectedText : '';
+                if (url) lines.push(`  url: ${url}`);
+                if (title) lines.push(`  title: ${title}`);
+                if (selectedText) {
+                    const clipped = selectedText.length > 4000 ? `${selectedText.slice(0, 4000)}…` : selectedText;
+                    lines.push('  BEGIN_UNTRUSTED_WEB_SNIPPET');
+                    lines.push(clipped);
+                    lines.push('  END_UNTRUSTED_WEB_SNIPPET');
+                }
+                continue;
+            }
+
+            if (kind === 'formField') {
+                const formId = typeof md?.formId === 'string' ? md.formId : undefined;
+                const fieldName = typeof md?.fieldName === 'string' ? md.fieldName : undefined;
+                const fieldLabel = typeof md?.fieldLabel === 'string' ? md.fieldLabel : undefined;
+                const value = typeof md?.value === 'string' ? md.value : '';
+                const inputType = typeof md?.inputType === 'string' ? md.inputType : undefined;
+                const options = Array.isArray(md?.options) ? md.options : [];
+                if (formId) lines.push(`  formId: ${formId}`);
+                if (fieldName) lines.push(`  field: ${fieldLabel ? `${fieldLabel} (${fieldName})` : fieldName}`);
+                if (inputType) lines.push(`  inputType: ${inputType}`);
+                if ((inputType === 'select' || inputType === 'radio') && options.length) {
+                    const rendered = options
+                        .slice(0, 30)
+                        .map((o: any) => {
+                            const v = typeof o?.value === 'string' ? o.value : '';
+                            const l = typeof o?.label === 'string' ? o.label : '';
+                            if (!v && !l) return '';
+                            return l && v ? `${l} (${v})` : (l || v);
+                        })
+                        .filter(Boolean)
+                        .join(', ');
+                    if (rendered) lines.push(`  options: ${rendered}${options.length > 30 ? '…' : ''}`);
+                }
+                if (value) lines.push(`  value: ${value.length > 1000 ? `${value.slice(0, 1000)}…` : value}`);
+                continue;
+            }
+
+            if (kind === 'formSnapshot') {
+                const formId = typeof md?.formId === 'string' ? md.formId : undefined;
+                const formName = typeof md?.formName === 'string' ? md.formName : undefined;
+                const fields = Array.isArray(md?.fields) ? md.fields : [];
+                if (formId) lines.push(`  formId: ${formId}`);
+                if (formName) lines.push(`  formName: ${formName}`);
+                lines.push('  fields:');
+                for (const f of fields.slice(0, 50)) {
+                    const name = typeof f?.name === 'string' ? f.name : 'unknown';
+                    const label = typeof f?.label === 'string' ? f.label : undefined;
+                    const value = typeof f?.value === 'string' ? f.value : '';
+                    const inputType = typeof f?.inputType === 'string' ? f.inputType : undefined;
+                    const options = Array.isArray(f?.options) ? f.options : [];
+                    const clipped = value.length > 1000 ? `${value.slice(0, 1000)}…` : value;
+                    const meta: string[] = [];
+                    if (inputType) meta.push(`type=${inputType}`);
+                    if ((inputType === 'select' || inputType === 'radio') && options.length) {
+                        const opts = options
+                            .slice(0, 20)
+                            .map((o: any) => typeof o?.value === 'string' ? o.value : '')
+                            .filter(Boolean)
+                            .join('|');
+                        if (opts) meta.push(`options=${opts}${options.length > 20 ? '|…' : ''}`);
+                    }
+                    lines.push(`    - ${label ? `${label} (${name})` : name}${meta.length ? ` [${meta.join(', ')}]` : ''}: ${clipped}`);
+                }
+                continue;
+            }
+
+            // Custom kind: prefer summary, fall back to minimal JSON.
+            const title = typeof md?.title === 'string' ? md.title : undefined;
+            const summary = typeof md?.summary === 'string' ? md.summary : undefined;
+            if (title) lines.push(`  title: ${title}`);
+
+            if (summary) {
+                lines.push(`  summary: ${summary.length > 4000 ? `${summary.slice(0, 4000)}…` : summary}`);
+                continue;
+            }
+            if (md?.data !== undefined) {
+                const json = JSON.stringify(md.data);
+                lines.push(`  data: ${json.length > 2000 ? `${json.slice(0, 2000)}…` : json}`);
+            }
+        }
+
+        if (lines.length) {
+            userContent.push({
+                type: "text",
+                text: `Context attachments (non-authoritative; user message is primary):\n ${lines.join('\n')}`
+            })
+        }
+        return userContent;
+    }
+
+    private static getAgentConfigs(contextKey: string): AgentConfig[] {
+        const agents = ConfigStore.getInstance().getAgentsForContext(contextKey);
+        if (!agents.length) {
+            throw new Error(`Agent configs not found for context key: ${contextKey}`);
+        }
+        return agents;
+    }
+
+    static async getAgentOptions(params: {
+        contextKey?: string,
+        messages?: ModelMessage[],
+        modelId?: string,
+        context?: AdditionalContext,
+        agentName?: string,
+    }, options: Omit<GenerateTextOptions, 'messages' | 'system'> = {}): Promise<Omit<GenerateTextOptions, 'messages'> & {name: string}> {
+        const { contextKey, messages, modelId, context, agentName } = params;
+        let agentConfig = ConfigStore.getInstance().getAgentConfigByName(agentName);
+        if (contextKey && messages) {
+           agentConfig = await AIHelper.selectAgentConfig(contextKey, messages);
+        }
+        const aiService = new AIService(ModelStore.getInstance());
+        const agentOptions = aiService.getAgentOptions(agentConfig, modelId, context);
+        return {
+            ...agentOptions,
+            ...options,
+        }
+    }
+
+    private static async selectAgentConfig(contextKey: string, messages: ModelMessage[]): Promise<AgentConfig> {
+        const configs = AIHelper.getAgentConfigs(contextKey)
+        if (configs.length === 1) {
+            return configs[0];
+        }
+        const aiService = new AIService(ModelStore.getInstance());
+        const systemPrompt = `Select the most appropriate agent for the given user prompt.
+Return only the agent name, no quotes or extra text.
+Available agents: ${
+        JSON.stringify(configs.map(config => ({ 
+            name: config.name, 
+            description: config.description, 
+            tools: config.tools.map(({data}) => data.title) })))
+        }`;
+        const agentName = await aiService.generateText({
+            messages,
+            system: systemPrompt,
+            temperature: 0.7,
+            maxOutputTokens: 2000
+        });
+
+        const agent = configs.find(config => config.name === agentName) as AgentConfig;
+        if (!agent) {
+            // fallback, agent not found, grabbing first from the list
+            return configs[0];
+        }
+        return agent;
+    }
+
+    static async getAssistantResponse(messages: Pick<AgentMessage, 'role' | 'content' | 'attachments'>[], signal?: AbortSignal, options: Omit<GenerateTextOptions, 'messages'> = {}): Promise<string> {
+        try {
+            const aiService = new AIService(ModelStore.getInstance());
+            const processedOptions = this.processToolChoice(options, messages);
+
+            return aiService.generateText({
+                temperature: 0.7,
+                maxOutputTokens: 2000,
+                ...processedOptions,
+                messages: await AIHelper.convertMessages(messages),
+                signal,
+            });
+        } catch (error) {
+            logger.error('AI assistant response generation failed:', error);
+            throw error;
+        }
+    }
+
+    private static processToolChoice(
+        options: Omit<StreamTextOptions, 'messages'> | undefined,
+        agentMessages: Pick<AgentMessage, 'role' | 'content' | 'toolCalls'>[]
+    ): Omit<StreamTextOptions, 'messages'> {
+        if (!options?.toolChoice) {
+            return options || {};
+        }
+
+        // Find the latest assistant message
+        const latestAssistantMessage = [...agentMessages]
+            .reverse()
+            .find(msg => msg.role === MessageRole.Assistant);
+
+        // Handle 'required' toolChoice: if any tool was called, set to 'auto'
+        if (options.toolChoice === 'required') {
+            const anyToolWasCalled = (latestAssistantMessage?.toolCalls?.length ?? 0) > 0;
+            if (anyToolWasCalled) {
+                return {
+                    ...options,
+                    toolChoice: 'auto' as const
+                };
+            }
+            return options;
+        }
+
+        // Handle specific tool toolChoice: if that specific tool was called, set to 'auto'
+        if (typeof options.toolChoice === 'object' && options.toolChoice.type === 'tool') {
+            const toolName = options.toolChoice.toolName;
+            const toolWasCalled = latestAssistantMessage?.toolCalls?.some(
+                toolCall => toolCall.name === toolName
+            ) ?? false;
+
+            if (toolWasCalled) {
+                return {
+                    ...options,
+                    toolChoice: 'auto' as const
+                };
+            }
+        }
+
+        return options;
+    }
+
+    static async streamAssistantResponse(
+        agentMessages: Pick<AgentMessage, 'role' | 'content' | 'toolCalls' | 'attachments'>[],
+        signal?: AbortSignal,
+        options?: Omit<StreamTextOptions, 'messages'>): Promise<ReturnType<typeof streamText>> {
+        const aiService = new AIService(ModelStore.getInstance());
+        const messages = await this.convertMessages(agentMessages)
+        const processedOptions = this.processToolChoice(options, agentMessages);
+
+        return aiService.streamText({
+            messages,
+            temperature: 0.7,
+            maxOutputTokens: 2000,
+            signal,
+            ...processedOptions
+        });
+    }
+
+    static async convertMessages(agentMessages: Pick<AgentMessage, 'role' | 'content' | 'toolCalls' | 'attachments'>[], ignoreToolsAndAttachments = false): Promise<ModelMessage[]> {
+        const result: ModelMessage[] = [];
+
+        for (const msg of agentMessages) {
+            if (msg.role === MessageRole.User) {
+                result.push({
+                    role: 'user',
+                    content: await this.convertUserMessage(msg, ignoreToolsAndAttachments)
+                });
+            }
+            if (msg.role === MessageRole.Assistant) {
+                const assistantMessage = {
+                    role: 'assistant' as const,
+                    content: [] as Array<TextPart | FilePart | ReasoningPart | ToolCallPart | ToolResultPart>
+                }
+                if (msg.content.trim().length) {
+                    assistantMessage.content.push({type: 'text', text: msg.content})
+                }
+                const toolMessage: ToolModelMessage = {
+                    role: 'tool',
+                    content: []
+                }
+                if(!ignoreToolsAndAttachments) {
+                    msg.toolCalls?.forEach((toolCall) => {
+                        if (toolCall.output) {
+                            assistantMessage.content.push({
+                                type: 'tool-call',
+                                toolCallId: toolCall.id,
+                                toolName: toolCall.name,
+                                input: toolCall.input
+                            })
+                            toolMessage.content.push({
+                                type: 'tool-result',
+                                toolCallId: toolCall.id,
+                                toolName: toolCall.name,
+                                output: {
+                                    type: 'text',
+                                    value: JSON.stringify(toolCall.output)
+                                }
+                            })
+                        }
+                    })
+                }
+                if (assistantMessage.content.length) {
+                    result.push(assistantMessage)
+                    if (toolMessage.content.length) {
+                        result.push(toolMessage)
+                    }
+                }
+            }
+        }
+
+        return result;
+    }
+
+    static async generateTitleForMessage(contextKey: string, messages: Pick<AgentMessage, 'role' | 'content'>[]): Promise<string> {
+        try {
+            const aiService = new AIService(ModelStore.getInstance());
+            const systemPrompt = `Generate descriptive title 5 words maximum for a chat conversation. Return only the title, no quotes or extra text. If user question is opaque, assume it is related to ${contextKey} topic.`;
+            return aiService.generateText({
+                messages: await AIHelper.convertMessages(messages, true),
+                system: systemPrompt,
+            });
+        } catch (error) {
+            logger.warn('AI title generation failed, falling back to simple title generation', { error });
+            return `${contextKey} session ${new Date().toISOString()}`;
+        }
+    }
+}

package/src/helpers/ConfigHelper.ts

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import type { AgentAppConfig, AgentTool } from '@multiplayer-app/ai-agent-types';
+import { AgentToolType } from '@multiplayer-app/ai-agent-types';
+import { logger } from '../libs/logger';
+
+export class ConfigHelper {
+
+  static loadConfig(rawConfig: Record<string, any>): AgentAppConfig {
+    try {
+      // Convert to AgentAppConfig format
+      return ConfigHelper.convertToAgentAppConfig(rawConfig);
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        logger.error(`Failed to parse config.json: ${error.message}`);
+        throw new Error(`Invalid JSON in config file: ${error.message}`);
+      }
+      logger.error(`Failed to load config: ${error}`);
+      throw error;
+    }
+  }
+
+  private static jsonSchemaToZod (schema: any): z.ZodSchema<any> | null {
+    if (!schema) return null;
+    return z.fromJSONSchema(schema);
+  }
+
+  /**
+   * Converts raw JSON config to AgentAppConfig format
+   * Validates structure and converts JSON schemas to Zod schemas
+   */
+  private static convertToAgentAppConfig(rawConfig: any): AgentAppConfig {
+    // Convert agents, transforming JSON schemas to Zod schemas
+    const config: AgentAppConfig = rawConfig.agents.reduce((config: AgentAppConfig, agent: any) => {
+      agent.contextKeys.forEach((contextKey: string) => {
+        if (!config[contextKey]) {
+          config[contextKey] = [];
+        }
+        config[contextKey].push({
+            name: agent.name,
+            description: agent.description,
+            defaultModel: agent.defaultModel,
+            systemPrompt: agent.systemPrompt,
+            temperature: agent.temperature || 0.1,
+            maxTokens: agent.maxTokens || 2000,
+            tools: agent.tools.map((tool: any) => ConfigHelper.convertTool(tool)),
+            outputSchema: agent.outputSchema ? ConfigHelper.jsonSchemaToZod(agent.outputSchema) as any : undefined
+        });
+      });
+      return config;
+    }, {} as AgentAppConfig);
+
+    return config
+  }
+
+  /**
+   * Converts a tool from JSON format (with JSON schemas) to AgentTool format (with Zod schemas)
+   */
+  private static convertTool(tool: any): AgentTool {
+    if (tool.type === AgentToolType.WEB_SEARCH) {
+      return {
+        type: AgentToolType.WEB_SEARCH,
+        data: {
+          title: AgentToolType.WEB_SEARCH,
+        }
+      };
+    }
+
+    if (tool.type === AgentToolType.API_TOOL) {
+      return {
+        type: AgentToolType.API_TOOL,
+        data: {
+          title: tool.data.title,
+          description: tool.data.description,
+          headersToPass: tool.data.headersToPass,
+          method: tool.data.method,
+          url: tool.data.url,
+          body: tool.data.body ? ConfigHelper.jsonSchemaToZod(tool.data.body) as any : undefined,
+          queryParams: tool.data.queryParams ? ConfigHelper.jsonSchemaToZod(tool.data.queryParams) as any : undefined,
+          needsApproval: tool.data.needsApproval ?? false,
+        }
+      };
+    }
+
+    throw new Error(`Unknown tool type: ${tool.type}`);
+  }
+
+
+  /**
+   * Validates the AgentAppConfig structure
+   * @throws Error if validation fails
+   */
+  private static validateConfig(config: AgentAppConfig): void {
+    if (!config.agents || !Array.isArray(config.agents)) {
+      throw new Error('Config must have an "agents" array');
+    }
+
+    if (!config.contexts || typeof config.contexts !== 'object') {
+      throw new Error('Config must have a "contexts" object');
+    }
+
+    // Validate agents
+    const agentNames = new Set<string>();
+    for (const agent of config.agents) {
+      if (!agent.name) {
+        throw new Error('All agents must have a "name" field');
+      }
+      if (agentNames.has(agent.name)) {
+        throw new Error(`Duplicate agent name found: ${agent.name}`);
+      }
+      agentNames.add(agent.name);
+
+      if (!agent.systemPrompt) {
+        throw new Error(`Agent "${agent.name}" must have a "systemPrompt" field`);
+      }
+    }
+
+    // Validate contexts reference valid agents
+    for (const [contextKey, contextAgentNames] of Object.entries(config.contexts)) {
+      if (!Array.isArray(contextAgentNames)) {
+        throw new Error(`Context "${contextKey}" must have an array of agent names`);
+      }
+
+      for (const agentName of contextAgentNames) {
+        if (!agentNames.has(agentName)) {
+          throw new Error(`Context "${contextKey}" references unknown agent: ${agentName}`);
+        }
+      }
+    }
+  }
+}